Video generation API

Video generation is an asynchronous task: submitting returns a task ID right away; poll the task status, then download the video once it completes. Only video generation models (priced per second in the model catalog) can use these endpoints; calling them with a chat model returns 400.

Each video model supports one or both protocols; the "How to call" section on the model page lists the endpoints that model accepts. An endpoint the model does not support returns 400 with a hint to the right one — the platform never switches protocols for you.

You can pass either the full model ID from the catalog or the official ID without the namespace (such as <model-id>).

Lifecycle and billing

1. Submit: funds for "requested seconds × price per second" are put on hold (pre-authorization). With insufficient balance you get 402 insufficient_balance and no task is created.
2. Generating: status moves queued → in_progress. The held amount is shown in the console under Usage → Request log → Video generation tasks.
3. Completed: settled once on the seconds actually generated (never more than requested); the rest of the hold is released. The charge then appears in the request log under its request_id.
4. Failed / cancelled / timed out: not billed; the whole hold is released.

The platform keeps advancing unfinished tasks in the background — settlement does not depend on you polling.

Protocol 1: OpenAI Videos (/v1/videos)

Submit

POST https://api.admesh.ai/v1/videos

curl https://api.admesh.ai/v1/videos \
  -H "Authorization: Bearer $ADMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "prompt": "A corgi running on the beach at sunset, cinematic",
    "seconds": "8"
  }'

Returns a video object; id is the task ID (video_…):

{ "id": "video_8f2a…", "object": "video", "model": "<model-id>", "status": "queued", "progress": 0, "seconds": "8", "created_at": 1762650000 }

Poll status

curl https://api.admesh.ai/v1/videos/$VIDEO_ID \
  -H "Authorization: Bearer $ADMESH_API_KEY"

status is queued / in_progress / completed / failed. When completed, seconds is the billed duration; on failure error.code gives the reason.

Download

curl -L https://api.admesh.ai/v1/videos/$VIDEO_ID/content \
  -H "Authorization: Bearer $ADMESH_API_KEY" \
  -o video.mp4

Only completed tasks can be downloaded. Optional query parameter variant=video|thumbnail|spritesheet (if the model supports it).

List and delete

• GET /v1/videos: list your recent video tasks.
• DELETE /v1/videos/{id}: delete a video task.

Protocol 2: Task API (/v1/video/generations)

Submit

curl https://api.admesh.ai/v1/video/generations \
  -H "Authorization: Bearer $ADMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "prompt": "A corgi running on the beach at sunset, cinematic",
    "duration": 5
  }'

Returns { "task_id": "video_…", "id": "video_…", "status": "queued", … }.

Poll status

curl https://api.admesh.ai/v1/video/generations/$TASK_ID \
  -H "Authorization: Bearer $ADMESH_API_KEY"

Returns { "code": "success", "data": { "task_id": "…", "status": "IN_PROGRESS", "progress": "40%", … } }. data.status is QUEUED / IN_PROGRESS / SUCCESS / FAILURE; on SUCCESS, data.result_url is the download URL (the same /v1/videos/{id}/content endpoint, which also requires your API key).

Request fields

Only the following fields are accepted; do not send other parameters:

Field	Protocol	Description
model	Both	Required, video model ID
prompt	Both	Text prompt; required for OpenAI Videos, for the Task API give prompt and/or image
seconds	OpenAI Videos	Duration in seconds, string or integer (e.g. "8"); defaults to the model's default
duration	Task API	Duration in seconds, integer; defaults to the model's default
size	Both	Resolution, e.g. 1280x720 (allowed values depend on the model)
input_reference	OpenAI Videos	Reference image (image-to-video, if the model supports it)
image	Task API	Reference image (image-to-video, if the model supports it)

• Seconds must be a positive integer and no more than the model's maximum; some models only accept a few fixed durations (e.g. 5 / 10 s) — see the model page.
• stream is not supported; n must be 1 (one video per task).

Common errors

HTTP	code	Meaning
400	invalid_request	Not a video model / endpoint not supported by the model / invalid or too many seconds / downloading before completion
401	invalid_api_key	API key invalid or revoked
402	insufficient_balance	Balance cannot cover "seconds × price per second"
403	model_not_allowed	This API key is not enabled for the model
404	not_found	Task does not exist or belongs to another account
429	rate_limit_exceeded	Rate limited, retry later
502 / 503 / 504	upstream_error / model_provider_unavailable / upstream_timeout	Temporarily unavailable; a submission that did not succeed is not billed

When a task fails, OpenAI Videos reports the reason in error.code (e.g. upstream_timeout means generation timed out) and the Task API in data.fail_reason. Failed tasks are not billed.