Getting started

The API is OpenAI-compatible. If your code already calls OpenAI, two settings are all that change.

  1. 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. 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 402 rather than queued.

  3. 3

    Point your client at us

    from openai import OpenAI
    
    client = OpenAI(
        base_url="https://omnirouter.li/v1",
        api_key="sk_live_...",
    )
  4. 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=True for 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

promptallWhat to generate — for voice, the text to speak. Required.
aspect_ratiovideo"landscape" (16:9, default) or "portrait" (9:16). Ignored with a start frame, which sets the shape.
duration_secvideoClip length in whole seconds, within the model's range (e.g. Seedance 2.0: 4–15). Veo is always 8.
start_image_urlvideoImage the clip starts from.
end_image_urlVeo, Seedance 2.0, Omni FlashImage the clip ends on; needs start_image_url.
reference_image_urlsVeo (3), Seedance 2.0 (9), Omni Flash (7)Characters, products or places to keep consistent.
languagevoiceISO code of the text, e.g. "en", "fr", "ar".
voicevoiceVoice 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-720pGrok Imagine 1.5 720p$0.035 / s
omni-flashOmni 1.1 Flash$0.02 / s
seedance-2-0-1080pSeedance 2.0 1080p ( RT)$0.305 / s
seedance-2-0-720pSeedance 2.0 ( RT)$0.165 / s
seedance-2-5-1080pSeedance 2.5 1080p (RT)$0.61 / s
seedance-2-5-480pSeedance 2.5 480p ( RT )$0.15 / s
seedance-2-5-720pSeedance 2.5 720p ( RT )$0.265 / s
seedance-2-5-miniSeedance 2.5 720p (md)$0.105 / s
seedance-2-5-mini-480pSeedance 2.5 480p (md)$0.0735 / s
seedance-2-fast-mdSeedance 2 Fast 720p (md)$0.0675 / s
seedance-2-fast-md-480pSeedance 2 Fast 480p (md)$0.0473 / s
seedance-2-mdSeedance 2 720p (md)$0.135 / s
seedance-2-md-480pSeedance 2 480p (md)$0.0745 / s
seedance-2-mini-480pSeedance 2 Mini 480p$0.0315 / s
seedance-2-mini-720pSeedance 2 Mini 720p$0.045 / s
veo-3-1Veo 3.1$0.03 / 8 s clip
veo-3-1-1080pVeo 3.1 1080p$0.075 / 8 s clip
eleven-multilingual-v2Eleven Multilingual v2$0.045 / 1K chars
eleven-v3Eleven v3$0.045 / 1K chars
eleven-v4Eleven 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/modelsModels available to your account
POST /v1/chat/completionsStreaming and non-streaming
POST /v1/responsesResponses API, for Codex and the responses wire protocol
POST /v1/images/generationsAccepted immediately, billed on completion
GET /v1/generations/{id}Poll an image job
POST /v1/jobsCreate a video or voiceover job
GET /v1/jobs/{id}Poll a video or voiceover job
POST /v1/jobs/{id}/cancelCancel a job; its reserved cost is released
GET /v1/voicesSearch 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.