Getting started
The API is OpenAI-compatible. If your code already calls OpenAI, two settings are all that change.
- 1
Create a key
Sign in, open API keys, and create one. The secret is shown once — we store only a hash, so it cannot be recovered afterwards.
- 2
Add credit
An account is free; usage is prepaid. Add credit under Billing before your first request. Accounts start at a zero balance and there is no trial credit, so a request made first is refused with
402rather than queued. - 3
Point your client at us
from openai import OpenAI client = OpenAI( base_url="https://omnirouter.li/v1", api_key="sk_live_...", ) - 4
Make a request
completion = client.chat.completions.create( model="deepseek-v4-1-flash", messages=[{"role": "user", "content": "Hello"}], ) print(completion.choices[0].message.content)Set
stream=Truefor server-sent events. Token usage arrives in the final frame.
Video and voice
Video and voiceover models run as jobs: you create one, get an id back immediately, and poll until the result is ready. Video takes a few minutes (longer at busy times); voice usually under a minute. Use the same sk_live_ key as for chat. The cost is reserved from your balance when the job is created and settled when it finishes — a job that fails is never charged.
1. Create a video job
curl https://omnirouter.li/v1/jobs \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3-1",
"input": {
"prompt": "A lighthouse on a rocky coast at dawn, slow push-in",
"aspect_ratio": "landscape"
}
}'The answer is 201 with the job. Keep its id:
{
"id": "6f1d2c9e-4b7a-4c1e-9a53-0d8e7f2b1a64",
"object": "job",
"model": "veo-3-1",
"status": "queued",
"cost": "0.03000000",
"cost_is_final": false,
"currency": "USD",
"queue_position": null,
"output": null,
"error": null
}2. Poll until it finishes
curl https://omnirouter.li/v1/jobs/6f1d2c9e-4b7a-4c1e-9a53-0d8e7f2b1a64 \ -H "Authorization: Bearer sk_live_..."
status moves from queued to processing to succeeded, or ends as failed, canceled or expired. Poll every 10 seconds for video and every 5 for voice — polling faster does not make a job finish sooner. While queued, queue_position shows where you stand. When it succeeds, output.url is the file and cost is the final charge:
{
"id": "6f1d2c9e-4b7a-4c1e-9a53-0d8e7f2b1a64",
"status": "succeeded",
"output": {
"type": "video",
"url": "https://.../clip.mp4",
"mime_type": "video/mp4",
"duration_sec": 8
},
"cost": "0.03000000",
"cost_is_final": true
}The link is public and permanent; download anything you need to keep long-term. To stop a job that has not finished, send POST /v1/jobs/{id}/cancel — its reserved cost is released.
Voiceover
The same call with a voice model: prompt is the text to speak (up to 20,000 characters) and the result is one MP3. Set language to the language of the text — numbers and dates are read in it. voice is optional; omit it for the default voice.
curl https://omnirouter.li/v1/jobs \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"model": "eleven-v3",
"input": {
"prompt": "Welcome to our product tour. Let us get started.",
"language": "en",
"voice": "Ntd0iVwICtUtA6Fvx27M"
}
}'Find voice ids with GET /v1/voices?language=en (add q= to search by name). Each entry has an id, a name and a preview_url to listen to; use voices marked "free": true. A finished voiceover's output has type "audio", the MP3 url, its duration_sec and the chars billed.
In Python
import time
import requests
API = "https://omnirouter.li/v1"
HEADERS = {"Authorization": "Bearer sk_live_..."}
job = requests.post(f"{API}/jobs", headers=HEADERS, json={
"model": "veo-3-1",
"input": {"prompt": "A paper boat drifting down a rainy street"},
}).json()
while job["status"] in ("queued", "processing"):
time.sleep(10)
job = requests.get(f"{API}/jobs/{job['id']}", headers=HEADERS).json()
if job["status"] == "succeeded":
print(job["output"]["url"], "cost", job["cost"])
else:
print("not generated:", job["error"])Input fields
| prompt | all | What to generate — for voice, the text to speak. Required. |
| aspect_ratio | video | "landscape" (16:9, default) or "portrait" (9:16). Ignored with a start frame, which sets the shape. |
| duration_sec | video | Clip length in whole seconds, within the model's range (e.g. Seedance 2.0: 4–15). Veo is always 8. |
| start_image_url | video | Image the clip starts from. |
| end_image_url | Veo, Seedance 2.0, Omni Flash | Image the clip ends on; needs start_image_url. |
| reference_image_urls | Veo (3), Seedance 2.0 (9), Omni Flash (7) | Characters, products or places to keep consistent. |
| language | voice | ISO code of the text, e.g. "en", "fr", "ar". |
| voice | voice | Voice id from GET /v1/voices. Optional. |
Images are an https:// URL or an inline data:image/...;base64, URI — JPEG, PNG or WebP, up to 5 MB each. start_image_url and end_image_url cannot be combined with reference_image_urls. Resolution is part of the model id — veo-3-1 and veo-3-1-1080p are separate models at separate prices — so there is no resolution field to set. An unsupported field or value is refused with 400 and a message naming it, before anything is charged.
Models
| grok-imagine-1-5-720p | Grok Imagine 1.5 720p | $0.035 / s |
| omni-flash | Omni 1.1 Flash | $0.02 / s |
| seedance-2-0-1080p | Seedance 2.0 1080p ( RT) | $0.305 / s |
| seedance-2-0-720p | Seedance 2.0 ( RT) | $0.165 / s |
| seedance-2-5-1080p | Seedance 2.5 1080p (RT) | $0.61 / s |
| seedance-2-5-480p | Seedance 2.5 480p ( RT ) | $0.15 / s |
| seedance-2-5-720p | Seedance 2.5 720p ( RT ) | $0.265 / s |
| seedance-2-5-mini | Seedance 2.5 720p (md) | $0.105 / s |
| seedance-2-5-mini-480p | Seedance 2.5 480p (md) | $0.0735 / s |
| seedance-2-fast-md | Seedance 2 Fast 720p (md) | $0.0675 / s |
| seedance-2-fast-md-480p | Seedance 2 Fast 480p (md) | $0.0473 / s |
| seedance-2-md | Seedance 2 720p (md) | $0.135 / s |
| seedance-2-md-480p | Seedance 2 480p (md) | $0.0745 / s |
| seedance-2-mini-480p | Seedance 2 Mini 480p | $0.0315 / s |
| seedance-2-mini-720p | Seedance 2 Mini 720p | $0.045 / s |
| veo-3-1 | Veo 3.1 | $0.03 / 8 s clip |
| veo-3-1-1080p | Veo 3.1 1080p | $0.075 / 8 s clip |
| eleven-multilingual-v2 | Eleven Multilingual v2 | $0.045 / 1K chars |
| eleven-v3 | Eleven v3 | $0.045 / 1K chars |
| eleven-v4 | Eleven v4 | $0.045 / 1K chars |
Video is billed per second of output — Veo per fixed 8-second clip — and voice per character spoken. Try them in Studio without writing code.
Endpoints
| GET /v1/models | Models available to your account |
| POST /v1/chat/completions | Streaming and non-streaming |
| POST /v1/responses | Responses API, for Codex and the responses wire protocol |
| POST /v1/images/generations | Accepted immediately, billed on completion |
| GET /v1/generations/{id} | Poll an image job |
| POST /v1/jobs | Create a video or voiceover job |
| GET /v1/jobs/{id} | Poll a video or voiceover job |
| POST /v1/jobs/{id}/cancel | Cancel a job; its reserved cost is released |
| GET /v1/voices | Search voices by language or name |
Errors
Errors use OpenAI's envelope with a request_id for support. 402 means top up, 404 means the model is unknown or not enabled for you, and 503 means the gateway was unavailable — that request is not charged.