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.

Today every video model is served through Replicate, on the marketplace's own account: 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

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

Create a video

POST /v1/videos with a JSON body, 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.

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

{
  "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 }
}

Read, list and download

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.

Billing

Video models are billed at the provider's listed price for the job: 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), pass-through, with no margin. See Pricing & billing.

• 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 charged its reservation, as for any request a crash leaves open. The job itself continues, and GET /v1/videos/{id} still answers for it. A job the gateway follows for two hours without an end is also 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.

Models

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.

Errors

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 -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

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")

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

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 & billing · Errors