Video Generation

Video generation lets applications submit prompt-to-video tasks through AISIX while keeping caller authentication, model aliases, upstream credentials, rate limits, and content guardrails in one gateway path.

AISIX exposes an OpenAI-compatible video surface with three routes that mirror the provider-side asynchronous workflow: submit a task, poll its status, and download the result. The gateway holds no task state — the returned video ID encodes everything AISIX needs to route later status and download calls to the right provider.

In this guide, you will generate a video through AISIX using an Alibaba Model Studio video model and follow the task to a downloadable result.

Prerequisites

Before starting, prepare the following:

A running AISIX gateway that can serve proxy requests.
A caller API key that can access the video model alias.
A model alias whose configured provider is alibaba, zhipuai, or volcengine, with a provider key whose api_base reaches the provider's API. There is no built-in default base URL for these providers. The examples below use an Alibaba Model Studio model.

The examples use a model alias configured like the following. The upstream model name is a text-to-video model from the provider's catalog:

{
  "display_name": "wan-video-prod",
  "provider": "alibaba",
  "model_name": "wan2.7-t2v",
  "provider_key_id": "YOUR_PROVIDER_KEY_ID"
}

Create a Video Generation Task

Submit the task with the model alias, a prompt, and optionally a duration in seconds:

curl -sS -X POST "http://127.0.0.1:3000/v1/videos" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-video-prod",
    "prompt": "A miniature city built from cardboard comes alive at night.",
    "seconds": 5
  }'

AISIX resolves the alias, runs input guardrails on the prompt, reserves rate-limit capacity, and submits the task to the provider asynchronously. The response is a video job object:

{
  "id": "bW9kZWwtaWQtMTpkMkZ1TFhacFpHVnZMWEJ5YjJROnRhc2stMDE",
  "object": "video",
  "model": "wan-video-prod",
  "status": "queued",
  "progress": 0,
  "created_at": 1753257600,
  "seconds": "5"
}

The id value is an opaque gateway-issued video ID. Store it — the status and download routes take it as the path parameter.

Request fields:

Field	Required	Meaning
`model`	Yes	The AISIX model alias.
`prompt`	Yes	The text prompt for the video.
`seconds`	No	Video duration in seconds, as an integer or a numeric string. Forwarded as the provider's duration parameter.
`size`	No	Pixel dimensions as `WIDTHxHEIGHT`, for example `1280x720`. Forwarded as the pixel-size parameter for providers whose models accept explicit dimensions (Alibaba Wan, Zhipu CogVideoX). Volcengine Ark models express output dimensions as resolution and ratio quality tiers instead, so the value is validated but not forwarded and the provider default applies. Consult the provider's model documentation before setting it.

Unset optional fields are omitted from the upstream request entirely.

Poll the Task Status

Poll the task with the video ID until the status reaches a terminal value:

curl -sS "http://127.0.0.1:3000/v1/videos/YOUR_VIDEO_ID" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

A finished task reports completed and, when the provider states it, the actual video duration:

{
  "id": "bW9kZWwtaWQtMTpkMkZ1TFhacFpHVnZMWEJ5YjJROnRhc2stMDE",
  "object": "video",
  "model": "wan-video-prod",
  "status": "completed",
  "progress": 100,
  "created_at": 0,
  "seconds": "5"
}

The status field is a four-value enum. AISIX maps each provider's task states onto it. Some providers report no distinct queued state, so a submission may start directly at in_progress:

Status	Meaning
`queued`	The provider accepted the task and has not started it.
`in_progress`	The provider is generating the video.
`completed`	The video is ready to download.
`failed`	Generation failed, was canceled, or the provider no longer knows the task (for example, an expired task). The response carries an `error` object with the provider's `code` and `message` when available.

progress reports 0 until the task completes and 100 afterward; the provider does not expose an intermediate percentage. Because the gateway stores no task state, created_at is populated on the submit response only; poll responses report 0.

Download the Video

When the status is completed, request the content route. AISIX responds with a 302 redirect to the provider's video URL:

curl -sS -o /dev/null -w "%{http_code} %{redirect_url}\n" \
  "http://127.0.0.1:3000/v1/videos/YOUR_VIDEO_ID/content" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

The command should print the redirect status and the provider-hosted download URL:

302 https://provider-cdn.example.com/videos/task-01/out.mp4

Follow the redirect with curl -L -o video.mp4 … to save the file. AISIX only redirects to absolute http or https URLs; the download itself goes directly to the provider's storage and does not pass through the gateway.

If the task is not finished, the content route returns 400 with a message telling the caller to keep polling. If the task failed, it returns 400 with the provider's failure detail.

Rate Limits and Guardrails

The submit route reserves the caller API key layers and the model's limits — its inline rate_limit and any model-scope rate-limit policies — before the task reaches the provider, exactly like other modeled routes. See Rate Limits.

The status and content routes reserve only the caller API key layers. Task polling is deliberately exempt from model-level limits: a client that submits a task and then hits the model's submission cap can still poll that task to completion.

Input guardrails resolved for the request — whether attached to the model, the caller API key, the team, or the environment — scan the prompt before submission. A blocked prompt is rejected before any provider task is created and does not consume the model's rate-limit capacity.

Endpoint Behavior

The video ID is scoped by model access: callers whose API key cannot access the model alias receive 404 for that ID, and unknown or malformed IDs also return 404. The error type is video_not_found.
Supported providers are alibaba (Alibaba Model Studio Wan), zhipuai (Zhipu CogVideoX; the spelling zhipu is also accepted), and volcengine (Volcengine Ark Seedance). Submitting with a model alias of any other provider returns a not-implemented error.
If the provider key's api_base ends with the provider's OpenAI-compatible or versioned suffix (/compatible-mode/v1, /api/v1, or /v1 for Alibaba; /api/paas/v4 for Zhipu; /api/v3 for Volcengine Ark), AISIX derives the provider root automatically — an existing key configured for chat traffic works unchanged.
Each submission is recorded in usage logs with zero tokens. Duration-based cost accounting for video tasks is not yet applied to budgets.

Next Steps

You have now generated a video through the gateway's modeled video surface. For provider video APIs that AISIX has not modeled yet, use Provider Passthrough — model-level rate limits apply there as well when the request body names a configured model.

Prerequisites​

Create a Video Generation Task​

Poll the Task Status​

Download the Video​

Rate Limits and Guardrails​

Endpoint Behavior​

Next Steps​