9Router — Image & Video Generation API Docs

🔌

API Endpoints

All endpoints follow OpenAI-compatible conventions

POST /v1/images/generations

Generate images or videos. For video models (RunwayML, Leonardo, Weavy video models), the response uses the same format but the url fields point to video files. This endpoint handles all image and video generation requests.

Parameter	Type	Required	Description
model	string	required	Model identifier (e.g. `dall-e-3`, `weavy-kling`, `leo-sora-2`)
prompt	string	required	Text description of the image or video to generate
n	integer	optional	Number of images to generate. Default: 1. Max: 4 (provider-dependent)
size	string	optional	Output dimensions or aspect ratio. Format varies by provider — see per-provider details below
quality	string	optional	Quality preset. Values: `standard` \| `hd` (DALL-E 3), `low` \| `medium` \| `high` \| `auto` (GPT Image)
negative_prompt	string	optional	Elements to exclude from the output (supported by most non-OpenAI providers)
image_url	string	optional	Reference image URL or base64 data URI. Used for img2img conditioning or as video start frame
end_image_url	string	optional	End/last-frame image URL. For first-last-frame video models (Kling, Veo). Interpolates between `image_url` and `end_image_url`
duration	integer	optional	Video duration in seconds. Valid values are model-specific (e.g. 5/8/10 for Runway, 3–15 for Kling)
resolution	string	optional	Video resolution: `480p` \| `720p` \| `1080p` (Weavy video models)
aspect_ratio	string	optional	Explicit aspect ratio string (e.g. `16:9`). Some providers accept this instead of `size`

GET /v1/models/info?id={provider}/{modelId}

Returns full metadata for a single model including all supported parameters and their constraints.

# Example
GET /v1/models/info?id=weavy/weavy-kling
GET /v1/models/info?id=openai/dall-e-3
GET /v1/models/info?id=leonardo/leo-sora-2

GET /v1/models

Lists all available models in OpenAI-compatible format.

🔑

Authentication

Bearer token authentication, provider-dependent credential handling

ℹ️ 9Router uses a provider connection system. The API key or Bearer token you pass is the 9Router connection credential — not the upstream provider key directly. Credentials are mapped to provider accounts internally.

          
curl -X POST https://your-9router-host/v1/images/generations \
  -H "Authorization: Bearer YOUR_9ROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "weavy-kling",
    "prompt": "A cinematic drone shot over a misty mountain valley at sunrise",
    "size": "16:9",
    "duration": 10
  }'

📦

Request Format

JSON body with OpenAI-compatible fields plus extended provider params

Image Request

Video Request

Image-to-Image

First-Last Frame

{
  "model": "dall-e-3",
  "prompt": "A futuristic city skyline at sunset, 4K, dramatic lighting",
  "n": 1,
  "size": "1792x1024",
  "quality": "hd"
}

{
  "model": "weavy-kling",
  "prompt": "Slow motion waterfall in a tropical jungle, cinematic",
  "size": "16:9",
  "duration": 10,
  "resolution": "1080p"
}

{
  "model": "weavy-veo",
  "prompt": "Add gentle camera movement, reveal the horizon",
  "size": "16:9",
  "image_url": "https://example.com/start-frame.jpg",
  "duration": 8
}

{
  "model": "weavy-kling-2-5-first-last-frame",
  "prompt": "Smooth transition between the two frames",
  "size": "16:9",
  "image_url": "https://example.com/first-frame.jpg",
  "end_image_url": "https://example.com/last-frame.jpg",
  "duration": 5
}

📤

Response Format

OpenAI-compatible response for both images and videos

{
  "created": 1735600000,
  "data": [
    {
      "url": "https://..."   // Direct URL to the generated image or video file
    }
  ]
}

created integer Unix timestamp of when the generation completed

data array Array of generated outputs. Length matches n parameter (usually 1)

data[].url string Direct URL to the generated image (PNG/JPEG) or video (MP4/WebM). Temporary — download promptly

🤖

OpenAI

DALL-E 3, DALL-E 2, GPT Image 1 — native OpenAI image generation

ℹ️ size accepts OpenAI pixel strings: 1024x1024, 1792x1024, 1024x1792, 512x512, 256x256

✨

Gemini (Google)

Imagen 3, Gemini Flash image generation

⚡

xAI Grok

Aurora image generation model by xAI

🌊

Stability AI

Stable Diffusion 3.5, SDXL, SD Ultra — industry-standard open diffusion models

ℹ️ size accepts aspect ratio strings: 1:1, 16:9, 9:16, 4:3, 3:2, etc.

🌲

Black Forest Labs (FLUX)

FLUX Pro, FLUX Dev, FLUX Schnell — state-of-the-art text-to-image

🔀

OpenRouter

Access multiple model providers through OpenRouter

⚡

fal.ai

Fast inference platform — FLUX, Ideogram, Recraft, and more

☁️

Cloudflare AI

Edge-deployed AI workers — fast, low-latency generation

🎭

MiniMax

MiniMax Image 01 — high-quality image generation

🍌

NanoBanana

Proprietary fast generation models

🖼️

SD WebUI

Local Stable Diffusion WebUI (AUTOMATIC1111) integration

⚠️ Requires a locally running SD WebUI instance. Configure the endpoint URL in 9Router settings.

🔧

ComfyUI

Local ComfyUI workflow integration

🤗

HuggingFace

HuggingFace Inference API models

🎨

Recraft

Recraft V3 — design-focused vector and illustration generation

🎬

RunwayML

Gen-4 Turbo, Gen-3 Alpha — professional AI video generation

ℹ️ RunwayML models with _image suffix route to image endpoints. Video models: duration options 5, 8, 10 seconds.

🎭

Leonardo AI

24 image models + 30 video models via Leonardo's GraphQL API

Image Generation (v1/v2)

v1 path: Phoenix, Flux Dev, Lucid Origin — uses modelId UUID + contrast. v2 path: Seedream, GPT Image, Flux Pro, native models — no modelId UUID required.

Video Generation

Kling, Veo, Sora, Hailuo, Seedance, LTX and more — routed via Leonardo's GraphQL Generate mutation. Adapter currently forwards: prompt, n, size, negative_prompt.

⚠️ For Leonardo video models, the adapter currently forwards prompt, n, size, and negative_prompt only. Additional video params (duration, image_url, etc.) are listed for future support.

Image Models (24)

Video Models (30)

🌊

Weavy

34 image models + 41 video models via Weavy's recipe execution API

How Weavy Works

Weavy executes AI workflows via a recipe/flow system. 9Router duplicates a template recipe, configures parameters, then polls for completion via a Python subprocess (weavy_generate.py).

Image Architecture

Image models use two paths: Predefined nodes (Flux Pro, Imagen 3, Gemini Nano) with native Weavy nodes, and Wildcard nodes (all FAL-ai based models) injected dynamically. The size ratio string is auto-converted to params.aspect_ratio internally.

Video Architecture

Video models use two routing paths: Predefined nodes (Runway, Kling, Seedance, Wan, Veo, LTX, Higgsfield) with direct duration mapping, and Wildcard nodes (all others) routing through fal.ai endpoints.

ℹ️ Weavy size parameter is always an aspect ratio string — NOT pixel dimensions. Valid values: 1:1 · 9:16 (portrait) · 16:9 (landscape) · 3:4 · 4:3. Backend auto-converts to the correct format per model (image_size, aspect_ratio, or pixel dimensions).

Image Models (34)

Video Models (41)

ℹ️ Text-only models (Hunyuan, Wan Video, Veo Text-to-Image variants): image_url is NOT supported.
First-last-frame models (Kling O1/2.5/2.1): use image_url for first frame and end_image_url for last frame.
Predefined duration models: service maps your value to nearest valid option.

📋

Model Info API

Query full parameter schema for any model programmatically

# Get full param schema for weavy-kling
curl https://your-9router-host/v1/models/info?id=weavy/weavy-kling

# Response
{
  "id": "weavy/weavy-kling",
  "name": "Kling 3.0",
  "kind": "video",
  "endpoint": "/v1/images/generations",
  "params": ["size", "duration", "resolution", "aspect_ratio", "image_url", "end_image_url"]
}

⚠️

Error Reference

Standard error response format

HTTP Status	Error Type	Description
400	`invalid_request_error`	Missing required parameters, invalid model ID, or unsupported parameter value
401	`authentication_error`	Invalid or missing API key / Bearer token
403	`permission_error`	Account does not have access to this model or provider
404	`not_found`	Model not found in registry
429	`rate_limit_error`	Provider rate limit or quota exceeded
500	`server_error`	Internal server error or upstream provider failure
504	`timeout`	Generation timed out. Video generation can take up to 10 minutes

// Error response format
{
  "error": {
    "message": "Model not found: invalid-model-id",
    "type": "not_found",
    "code": null
  }
}

💡

Code Examples

Ready-to-use code snippets

Python

JavaScript

cURL

from openai import OpenAI

client = OpenAI(
    api_key="your-9router-key",
    base_url="https://your-9router-host/v1"
)

# Generate an image
img = client.images.generate(
    model="weavy-flux-2-pro",
    prompt="A photorealistic cat sitting on a library shelf",
    size="16:9",
    n=1
)
print(img.data[0].url)

# Generate a video (uses same SDK, same endpoint)
vid = client.images.generate(
    model="weavy-kling",
    prompt="A cat playing with a ball of yarn, slow motion, cinematic",
    size="16:9",
    extra_body={"duration": 10, "resolution": "1080p"}
)
print(vid.data[0].url)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-9router-key',
  baseURL: 'https://your-9router-host/v1',
});

// Generate an image
const img = await client.images.generate({
  model: 'dall-e-3',
  prompt: 'A surreal landscape with floating islands at twilight',
  size: '1792x1024',
  quality: 'hd',
});
console.log(img.data[0].url);

// Generate a video (Weavy Veo 3.1 — fixed 8s)
const vid = await fetch('https://your-9router-host/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-9router-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'weavy-veo',
    prompt: 'Aerial view of a coral reef, underwater drone shot',
    size: '16:9',
    image_url: 'https://example.com/reef.jpg', // optional start frame
    duration: 8,
  }),
});
const data = await vid.json();
console.log(data.data[0].url);

# Image generation (DALL-E 3, landscape)
curl -X POST https://your-9router-host/v1/images/generations \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A neon-lit Tokyo street at night, rain reflections",
    "size": "1792x1024",
    "quality": "hd"
  }'

# Weavy image generation (portrait 9:16)
curl -X POST https://your-9router-host/v1/images/generations \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "weavy/weavy-flux-pro",
    "prompt": "A cute cat wearing a hat, studio photo",
    "size": "9:16"
  }'

# Video generation (Weavy Kling 3.0)
curl -X POST https://your-9router-host/v1/images/generations \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "weavy/weavy-kling",
    "prompt": "A slow pan across an ancient Roman amphitheater at golden hour",
    "size": "16:9",
    "duration": 10,
    "resolution": "1080p"
  }'

9Router API Reference