Console
API reference

Videos

Generate videos.

POST/v1/videos

Generate a video from a text prompt. This is the OpenAI Videos API surface: point client.videos.create at https://api.routerplus.com/v1 and the call works unchanged.

A video takes from ten seconds to several minutes to make, longer than any edge keeps a request open. So a video is a job. POST /v1/videos answers at once with the job; you read the job with GET /v1/videos/{id} until it is completed; then you download the MP4 from GET /v1/videos/{id}/content.

To try it without writing code, pick a video model in the playground.

Video models are served through Replicate and MachGen, on the marketplace's own accounts: a key bound to your own provider connection cannot make videos yet. Text-to-video only: image-to-video and reference images are not offered yet, and a request that sends one is refused.

Authentication

HeaderFormat
AuthorizationBearer tm_vk_... (the standard OpenAI-style header)
x-api-keytm_vk_... — also accepted, same key

A missing or invalid key returns 401 with error_type: "auth".

Create a video

POST /v1/videos with a JSON body, or the multipart/form-data form OpenAI's SDKs send (each field a string, read as the type the model declares), capped at 1 MB. Every rule below is checked before anything is reserved or sent to a provider, so a refused request has no ledger row and no charge.

ParameterTypeBehavior
modelstring, requiredA video model id — see Model discovery. A chat model here is a 400 naming the chat routes; an image model is a 400 naming /v1/images/generations; an id that is not a video model anywhere is a 404.
promptstring, requiredNon-empty, at most 32 000 characters.
secondsinteger, or a string of digitsThe length. OpenAI's SDKs send a string ("8"), and both forms are read the same way. Each model accepts a range (below). Omitted = the model's default length, which is always sent, so the job is billed for the length that was reserved.
durationintegerAnother name for seconds. Send one of the two; if you send both and they differ, it is a 400.
resolutionstringPer model, for example 480p, 720p, 1080p.
aspect_ratiostringPer model, for example 16:9, 9:16, 1:1.
sizestringExact pixels, for example 1280x720, on the models that declare sizes (seedance-2.5). Elsewhere it is dropped and recorded.
generate_audiobooleanOn the models that make sound. A MachGen model always tells MachGen: omitted, it is the model's default (in supported_parameters): on where sound costs nothing, off where it costs more.
enhance_promptbooleanMachGen models only: MachGen's prompt enhancement. Omitted, MachGen's default applies, which is on (MachGen says its newer video models lose quality without it). Elsewhere it is dropped and recorded.
seedintegerOn the models that declare one.
userstringYour end-user id, at most 256 characters. Kept with the job and returned on it; never sent to the provider.
providerobjectRouting controls read by the gateway and never forwarded — require_parameters and the rest, see Routing policies.

The accepted values are per model and published in /api/models.json under supported_parameters. A value outside a model's declared set is a 400 whose message starts with the field name and lists what that model accepts. An explicit null means "not provided", as on the other routes.

Refused, never dropped: input_reference, frame_images and input_references. To drop an image would make, and bill, a different video from the one asked for.

Dropped and recorded: any other key, including callback_url — the gateway does not send provider webhooks to your URL. The names are in the x-tm-dropped-params header and on the ledger row. Send "provider": {"require_parameters": true} to turn a drop into a 400 instead.

The answer is HTTP 200 with the video object, status: "queued". It carries the same headers as an image response: x-request-id, x-tm-provider, x-tm-attempts, x-tm-upstream-status, and x-tm-dropped-params when something was dropped. The provider has 60 seconds to accept the job; past that the request is a 504 upstream_error.

The video object

json
{
  "id": "video_7f3c2a9b1e4d4c6a8b0f2e1d3c5a7b9e",
  "object": "video",
  "model": "wan-3",
  "status": "completed",
  "progress": 100,
  "created_at": 1790000000,
  "completed_at": 1790000094,
  "expires_at": null,
  "seconds": "5",
  "size": null,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "error": null,
  "usage": { "cost": 0.5 }
}
FieldMeaning
idOurs, video_ and 32 hex digits. It is never the provider's id.
statusqueued → in_progress → completed or failed.
progress0 until the video is done, then 100. The providers report no progress, and the gateway does not invent one.
secondsA string, as in OpenAI's object.
errorOn a failed job: {code, message}. The code is one of video_generation_failed, content_policy_violation, video_cancelled, video_expired, video_timeout. The provider's own words are never kept.
usage.costUSD, once the job has ended: the charge. Absent while the job runs, and on static dev keys.
userYour user, when you sent one.

Read, list and download

CallAnswer
GET /v1/videos/{id}The video object. Ask every few seconds; a job takes minutes.
GET /v1/videosYour organization's videos, newest first: {object: "list", data, first_id, last_id, has_more}. Query: limit (1–100, default 20), order (desc or asc), after (a video id).
GET /v1/videos/{id}/contentThe MP4, streamed from the provider. ?variant=video is the only variant (anything else is a 400). A Range header is passed on, so a player can seek; a range the provider cannot satisfy is a 416. Before the job is completed it is a 409. A file the provider no longer keeps is a 410.

The gateway follows a job itself: it asks the provider every 5 seconds for the first two minutes, then every 10 seconds, then every 20. A read between two of those asks shows the last status the gateway knows. A video of another organization is a 404, exactly like a video that does not exist. The file is streamed through as it arrives, with the provider's content-type (else video/mp4), content-length, content-range and accept-ranges, and is never stored by the marketplace — save it when you download it. Replicate keeps a video's file for about an hour after it is done: on its models expires_at says until when, and a later download is a 410 not_found. MachGen states no limit, so expires_at stays null there.

Billing

Video models are billed at the provider's listed price for the job, pass-through, with no margin. See Pricing.

  • Replicate's models: Replicate's published price per second of video, for the seconds Replicate says it billed (never more than 5% past the length you asked for).

  • MachGen's models (machgen/...): MachGen's published price per second for the length, resolution and sound you asked for, less the model's own credit-back (15% on most partner models, none on MiniMax, LTX, Vidu and Wan 2.2), which is what MachGen bills the marketplace. Where MachGen's price per second changes along the video, each second is billed at its own rate: 6 seconds of machgen/vidu-q3-turbo at 540p cost 5 × $0.015 + 1 × $0.018 = $0.093.

  • Reserve, before the job is submitted: seconds × the model's per-second ceiling. The models page shows that ceiling as Per second ≤. Your balance must cover it.

  • Settle, when the job ends: the reported cost, exactly. The hold is then released.

  • A failed, cancelled or expired job costs nothing. You get no video, so you pay nothing.

  • A completed job without a reported cost is charged its reservation, marked estimated in GET /v1/generation.

  • If the gateway restarts while a job runs, the job is first charged its reservation, as for any request a crash leaves open. The job itself continues, and GET /v1/videos/{id} (or the list) still answers for it: when a read finds it ended, the charge is brought down to what the provider billed ($0 for a failed job) and the difference is credited back to your balance, once. A job the gateway follows for two hours without an end is charged its reservation, and ends failed with the code video_timeout.

Worked numbers on wan-3 (per-second ceiling $0.105): a 5-second request reserves $0.525 (5 × $0.105). At 480p Replicate bills $0.025 a second, so the charge is $0.125 and the rest of the hold is released. On machgen/kling-v3 (per-second ceiling $0.396, its 4k rate): a 5-second 720p request without sound reserves $1.98 and is charged 5 × $0.08 less 15%, $0.34.

Models

Through Replicate

Model idMade byLengthResolutionsSoundListed pricePer second ≤
wan-3Alibaba2–30 s (default 5)480p, 720p, 1080pprovider default; no audio toggle$0.025/s at 480p, $0.05/s at 720p, $0.10/s at 1080p$0.105
grok-imagine-videoxAI1–15 s (default 5)480p, 720pprovider default; no audio toggle$0.05/s$0.0525
seedance-2.0ByteDance4–15 s (default 5)480p, 720p, 1080pyes, at no extra cost$0.08/s at 480p, $0.18/s at 720p, $0.45/s at 1080p$0.48
seedance-2.0-fastByteDance4–15 s (default 5)480p, 720pyes, at no extra cost$0.07/s at 480p, $0.15/s at 720p$0.16
kling-v3-videoKuaishou3–15 s (default 5)720p, 1080p, 4kgenerate_audio, off by default$0.168/s at 720p ($0.252 with sound), $0.224/s at 1080p ($0.336 with sound), $0.42/s at 4k$0.441
veo-3.1-fastGoogle4, 6 or 8 s (default 8)720p, 1080pon by default; generate_audio: false turns it off$0.15/s with sound, $0.10/s without$0.158
veo-3.1Google4, 6 or 8 s (default 8)720p, 1080pon by default; generate_audio: false turns it off$0.40/s with sound, $0.20/s without$0.42
veo-3.1-liteGoogle4, 6 or 8 s (default 8)720p, 1080pprovider default; no audio toggle$0.05/s at 720p, $0.08/s at 1080p$0.084
wan-3-primeAlibaba2–30 s (default 5)480p, 720p, 1080pprovider default; no audio toggle$0.068/s at 480p, $0.14/s at 720p, $0.28/s at 1080p$0.294
happyhorse-1.0Alibaba3–15 s (default 5)720p, 1080pprovider default; no audio toggle$0.14/s at 720p, $0.28/s at 1080p$0.294
happyhorse-1.1Alibaba3–15 s (default 5)720p, 1080pprovider default; no audio toggle$0.14/s at 720p, $0.18/s at 1080p$0.189
seedance-2.0-miniByteDance4–15 s (default 5)480p, 720pgenerate_audio$0.04/s at 480p, $0.09/s at 720p$0.095
seedance-2.5ByteDance4–30 s (default 5)480p, 720p (or an exact size)generate_audio$0.1028/s at 480p, $0.2312/s at 720p$0.30
flux-3-videoBlack Forest Labs5–20 s (default 5)720p, 1080pgenerate_audio$0.17/s at 720p, $0.29/s at 1080p$0.305
gen-4.5Runway5 or 10 s (default 5)provider defaultprovider default; no audio toggle$0.12/s$0.126
hailuo-2.3MiniMax6 or 10 s (default 6)768p, 1080pprovider default; no audio toggleper video: $0.28 (768p, 6 s), $0.56 (768p, 10 s), $0.49 (1080p, 6 s)$0.082

Audio follows the provider defaults for Wan 3 and Grok Imagine Video; this API exposes no audio toggle for those models.

Sora 2 was retired on September 24, 2026 and is no longer offered. Existing video and usage records remain readable. See OpenAI’s discontinuation notice.

Prices are Replicate's published prices for each model, read on 2026-10-12. Replicate bills the video it returned, which can run a fraction of a second past the length asked for (5.04 s for 5 s); that fraction is billed, up to 5% of the length.

Through MachGen

What you pay per second (MachGen's list price less the model's credit-back). "s 1-15" is a rate for those seconds of the video. The default length, resolution and sound are in brackets or named.

Model idMade byLengthResolutionsSoundPrice per secondPer second ≤
machgen/wan-3.0Alibaba2–30 s (5)480p, 720p (default), 1080pon by default; no extra cost$0.04165 480p, $0.0816 720p, $0.16235 1080p$0.191
machgen/grok-imagine-videoxAI1–15 s (5)480p, 720p (default)none$0.05015 480p, $0.07055 720p$0.083
machgen/happyhorse-1.0Alibaba3–15 s (5)720p (default), 1080pnone$0.1122 720p, $0.2244 1080p$0.264
machgen/happyhorse-1.1Alibaba3–15 s (5)720p (default), 1080pnone$0.1122 720p, $0.1445 1080p$0.17
machgen/kling-o3Kuaishou3–15 s (5)720p (default), 1080p, 4koff by default; costs more$0.068 720p, $0.0901 720p with sound, $0.0901 1080p, $0.1122 1080p with sound, $0.3366 4k, $0.3366 4k with sound$0.396
machgen/kling-v3Kuaishou3–15 s (5)720p (default), 1080p, 4koff by default; costs more$0.068 720p, $0.10115 720p with sound, $0.0901 1080p, $0.13515 1080p with sound, $0.3366 4k, $0.3366 4k with sound$0.396
machgen/kling-v4Kuaishou3–30 s (5)720p (default), 1080pnone$0.13345 720p, $0.19975 1080p$0.235
machgen/ltx-2.3-proLightricks6, 8, 10 s (6)1080p (default), 1440p, 4kon by default; no extra cost$0.03 1080p, $0.06 1440p, $0.1 4k$0.1
machgen/minimax-h3MiniMax1–30 s (5)480p, 768p (default), 1440pon by default; no extra cost$0.035 480p s 1-15, $0.0175 480p s 16-30, $0.04 768p s 1-15, $0.02 768p s 16-30, $0.1 1440p s 1-15$0.1
machgen/minimax-h3-omniMiniMax1–15 s (5)480p, 768p (default)on by default; no extra cost$0.02 480p, $0.02 768p$0.02
machgen/minimax-h3-turboMiniMax1–15 s (5)480p, 768p (default)on by default; no extra cost$0.015 480p, $0.015 768p$0.02
machgen/pixverse-c1PixVerse1–15 s (5)360p, 540p, 720p (default), 1080poff by default; costs more$0.02465 360p, $0.0323 360p with sound, $0.0323 540p, $0.0408 540p with sound, $0.0408 720p, $0.0527 720p with sound, $0.0765 1080p, $0.09605 1080p with sound$0.113
machgen/pixverse-v6PixVerse1–15 s (5)360p, 540p, 720p (default), 1080poff by default; costs more$0.0204 360p, $0.02805 360p with sound, $0.02805 540p, $0.03655 540p with sound, $0.03655 720p, $0.04845 720p with sound, $0.07225 1080p, $0.09265 1080p with sound$0.109
machgen/seedance-2.0ByteDance4–15 s (5)480p, 720p (default), 1080p, 4kon by default; no extra cost$0.059762 480p, $0.12852 720p, $0.318087 1080p, $0.66096 4k$0.7776
machgen/seedance-2.0-fastByteDance4–15 s (5)480p, 720p (default)on by default; no extra cost$0.047809 480p, $0.102816 720p$0.12096
machgen/seedance-2.0-miniByteDance4–15 s (5)480p, 720p (default)on by default; no extra cost$0.029881 480p, $0.06426 720p$0.0756
machgen/seedance-2.5ByteDance4–30 s (5)480p, 720p (default), 1080pon by default; no extra cost$0.08738 480p, $0.196452 720p, $0.483327 1080p$0.56862
machgen/veo-3.1Google4, 6, 8 s (6)720p (default), 1080p, 4kalways on$0.40035 720p, $0.40035 1080p, $0.6001 4k$0.706
machgen/veo-3.1-fastGoogle4, 6, 8 s (6)720p (default), 1080p, 4kalways on$0.1003 720p, $0.1207 1080p, $0.30005 4k$0.353
machgen/vidu-q3-proShengShu1–16 s (5)540p, 720p (default), 1080pon by default; no extra cost$0.053 540p, $0.118 720p, $0.142 1080p$0.142
machgen/vidu-q3-turboShengShu1–16 s (5)540p, 720p (default)on by default; no extra cost$0.015 540p s 1-5, $0.018 540p s 6-10, $0.02 540p s 11-16, $0.03 720p s 1-5, $0.04 720p s 6-10, $0.045 720p s 11-16$0.045
machgen/wan-2.2-t2v-a14bAlibaba5 s (5)480p, 720p (default)none$0.018 480p, $0.036 720p$0.036

Prices are MachGen's public pricebook, read on 2026-11-09. machgen/minimax-h3 renders 1440p up to 15 seconds only (MachGen refuses a longer 1440p video, 2026-11-20): a longer 1440p request is refused before anything is reserved, with a 400 that says so and names the resolutions that make that length (480p, 768p). machgen/minimax-h3-turbo is at MachGen's promotional price until January 1, 2027, after which it is $0.02 a second. MachGen's image-to-video models are not offered yet.

Errors

CaseStatuserror_typeBilled
A field outside the model's accepted values, an image input, a chat or image model on this route400invalid_requestno row
The model is listed but has no price row400model_not_pricedno row
A MachGen model's price table has no price for the length, resolution and sound asked for400invalid_request: the message starts seconds: and names the longest video at that resolution and the resolutions that make the length asked (seconds: 1440p videos are at most 15 seconds long on this model; ask for 15 seconds or fewer. For 16 seconds, use 480p or 768p.)no row
Not a video model in the catalog404model_unavailableno row
Request body over 1 MB413request_too_largeno row
Unknown id, or another organization's video404not_found—
The file before the job is completed409invalid_request—
Key RPM or a shared limit, balance too low for the reservation, or a monthly spend cap429rate_limit / insufficient_quotano row
The provider refused the submitthe provider'supstream_error$0
The provider did not accept the job within 60 s504upstream_error$0; x-should-retry: false (the provider may hold the job: the request is not sent elsewhere, and OpenAI's SDKs do not retry it)
The provider accepted the job but named no job id, or its answer could not be read502upstream_error$0
Every deployment serving the model is cooling down503model_unavailablenothing dispatched; retry-after: 5
The provider did not send the file on a download502upstream_error—
The provider accepted the job but it failed200 on the read; status: "failed"—$0

Bodies follow the OpenAI error envelope with the canonical class in error.metadata.error_type; a provider's own error body is never relayed. The reverse refusal also holds: a video model sent to POST /v1/chat/completions, POST /v1/messages or POST /v1/images/generations is a 400 naming /v1/videos.

Examples

curl
Create, read, download
curl -s https://api.routerplus.com/v1/videos \
  -H "Authorization: Bearer $TM_API_KEY" -H "content-type: application/json" \
  -d '{"model":"seedance-2.0-fast","prompt":"a paper boat drifting down a rainy street","seconds":"5"}'
# → {"id":"video_…","status":"queued",…}
curl -s https://api.routerplus.com/v1/videos/video_… -H "Authorization: Bearer $TM_API_KEY"
curl -s https://api.routerplus.com/v1/videos/video_…/content -H "Authorization: Bearer $TM_API_KEY" -o video.mp4
python
The official openai SDK with the base URL swapped
import os
import time
from openai import OpenAI

client = OpenAI(base_url="https://api.routerplus.com/v1", api_key=os.environ["TM_API_KEY"])

video = client.videos.create(model="wan-3", prompt="a lighthouse at dusk", seconds="5")
while video.status in ("queued", "in_progress"):
    time.sleep(5)
    video = client.videos.retrieve(video.id)
if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("video.mp4")
typescript
The official openai package
import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.routerplus.com/v1", apiKey: process.env.TM_API_KEY });

let video = await client.videos.create({ model: "veo-3.1-fast", prompt: "a fox leaping into snow", seconds: "4" });
while (video.status === "queued" || video.status === "in_progress") {
  await new Promise((r) => setTimeout(r, 5000));
  video = await client.videos.retrieve(video.id);
}
if (video.status === "completed") {
  const file = await client.videos.downloadContent(video.id);
  writeFileSync("video.mp4", Buffer.from(await file.arrayBuffer()));
}

The SDKs' types list OpenAI's own models and lengths; the gateway reads any model id and any whole number of seconds the model accepts.

Data policy

The gateway keeps a job's id, model, length, shape, status and charge so you can retrieve it later. The video file streams from the provider when downloaded. See Data policy for how request data is handled.

Model discovery

bash
curl -s "https://api.routerplus.com/v1/models?output_modalities=video" \
  -H "Authorization: Bearer $TM_API_KEY"

Every row of GET /v1/models carries architecture.output_modalities: ["text"], ["image"] or ["video"]. The public feed https://app.routerplus.com/api/models.json carries supported_parameters for each video model, max_output_tokens as its per-second ceiling in cost units (one micro-dollar each), and price_card, the provider's listed prices.

See also: POST /v1/images/generations · Pricing · Errors

For agents: /docs/api-videos.md and /llms.txt