视频生成

视频生成功能允许应用通过 AISIX 提交提示词生成视频任务，同时在同一网关路径中统一处理调用方身份认证、模型别名、上游凭证、限流和内容安全护栏。

AISIX 提供兼容 OpenAI 的视频接口，其中三条路由对应模型服务提供方侧的异步工作流：提交任务、轮询状态和下载结果。网关不保存任务状态；返回的视频 ID 已编码 AISIX 将后续状态查询和下载调用路由到正确模型服务提供方所需的全部信息。

本指南将使用 Alibaba Model Studio 视频模型通过 AISIX 生成视频，并持续跟踪任务直至结果可下载。

准备工作

请先准备以下内容：

一个可以处理代理请求的 AISIX 网关。
一个可以访问视频模型别名的调用方 API Key。
一个已配置受支持视频模型服务提供方的模型别名（参见端点行为）。除 OpenAI 外，每个模型服务提供方都需要配置 api_base 可访问其 API 的密钥；这些服务提供方没有内置默认 Base URL。如果 OpenAI 模型未设置 api_base，则回退到标准 OpenAI Base URL。以下示例使用 Alibaba Model Studio 模型。

示例使用如下模型别名。上游模型名称来自模型服务提供方目录中的文生视频模型：

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

创建视频生成任务

使用模型别名、提示词以及可选的视频时长（秒）提交任务：

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 会解析别名，对提示词执行输入安全护栏检查，预留限流容量，并向模型服务提供方异步提交任务。响应是一个视频任务对象：

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

id 是由网关签发的不透明视频 ID。请保存该值，状态和下载路由会将其用作路径参数。

请求字段：

字段	必填	含义
`model`	是	AISIX 模型别名。
`prompt`	是	用于生成视频的文本提示词。
`seconds`	否	视频时长（秒），可使用整数或数字字符串。它会作为模型服务提供方的时长参数转发（Alibaba、Zhipu、Volcengine Ark 和 Runway 使用 `duration`）。对 OpenAI，该值会以字符串形式作为 `seconds` 转发，Sora 仅接受 `4`、`8` 或 `12`。
`size`	否	`WIDTHxHEIGHT` 格式的像素尺寸，例如 `1280x720`。对于支持显式尺寸的模型（早期 Alibaba Wan 系列、Zhipu CogVideoX、OpenAI Sora），该值作为像素尺寸参数转发；对于 Runway，则转为等效的 `WIDTH:HEIGHT` 分辨率字符串。Volcengine Ark 模型和 Alibaba wan2.7 系列使用分辨率及宽高比质量层级表达输出尺寸；对于 Ark，此值会经过验证但不会转发，而是应用模型服务提供方默认值。设置前请查阅相应模型文档，每个模型服务提供方都会依据自身的模型值列表进行验证。

未设置的可选字段会从上游请求中完全省略。

轮询任务状态

使用视频 ID 轮询任务，直到状态达到终态：

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

任务完成时状态为 completed；如果模型服务提供方返回了实际视频时长，响应也会包含该值：

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

status 是包含四个值的枚举。AISIX 会将各模型服务提供方的任务状态映射到这些值。有些模型服务提供方没有单独的排队状态，因此任务提交后可能直接进入 in_progress：

状态	含义
`queued`	模型服务提供方已接受任务，但尚未开始。
`in_progress`	模型服务提供方正在生成视频。
`completed`	视频已可下载。
`failed`	生成失败、任务已取消，或模型服务提供方已无法识别该任务（例如任务已过期）。如果模型服务提供方提供了错误信息，响应会包含带有其 `code` 和 `message` 的 `error` 对象。

对于会返回真实完成百分比的模型服务提供方（OpenAI Sora），progress 会显示该值。对于不提供百分比的服务，该值在任务完成前为 0，完成后为 100。由于网关不存储任务状态，只有提交响应会填充 created_at；轮询响应会返回 0。

下载视频

当状态为 completed 时，请求内容路由。请使用 curl -L，使该命令适用于所有模型服务提供方。AISIX 会根据模型服务提供方交付成品文件的方式，重定向到其下载 URL，或自行流式传输视频：

curl -sS -L -o video.mp4 \
  "http://127.0.0.1:3000/v1/videos/YOUR_VIDEO_ID/content" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

两种路径保存的 MP4 相同，但在脚本处理响应时存在以下区别：

交付方式	模型服务提供方	内容路由返回值
重定向	Alibaba、Zhipu、Volcengine Ark、Runway	返回 `302`，`Location` 请求头指向模型服务提供方签名的下载 URL。文件直接从模型服务提供方的存储传输到客户端，不经过网关。AISIX 仅重定向到绝对 `http` 或 `https` URL。
网关流式传输	OpenAI	返回 `200` 和 MP4 字节、模型服务提供方的 `Content-Type`（通常为 `video/mp4`）以及 `Content-Disposition` 附件请求头。模型服务提供方要求使用其凭证下载文件，因此 AISIX 会使用配置的模型服务提供方密钥获取文件并流式转发字节。调用方不会接触到模型服务提供方凭证。

流式响应逐块经过网关，不会完整保存在内存中，因此大文件不会增加网关内存用量。每次分块读取受模型的流超时限制：如果较慢的上游停滞，传输会在正文中途终止。模型服务提供方声明 Content-Length 时，网关会原样转发；此时中断的传输会被客户端识别为长度不足，请重试内容请求。

如需检查某个模型服务提供方使用的路径，请让 curl 在不跟随重定向的情况下输出状态：

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"

使用重定向的模型服务提供方会输出重定向状态和由其托管的 URL：

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

使用网关流式传输的模型服务提供方会输出 200，重定向 URL 为空。在该路径上，此探测会将完整文件传输到 /dev/null，因此请使用较小的任务：

如果任务尚未完成，内容路由返回 400，并提示调用方继续轮询。如果任务失败，它会返回 400 和模型服务提供方的失败详情。模型服务提供方下载端点返回的错误始终使用 JSON 错误封装，不会表现为截断的视频正文。

限流和安全护栏

提交路由会在任务到达模型服务提供方之前，预留调用方 API Key 各层级和模型限制的容量，包括模型的内联 rate_limit 以及模型作用域的限流策略，与其他建模路由一致。参见限流。

状态和内容路由仅预留调用方 API Key 各层级的容量。任务轮询特意不受模型级限制：客户端提交任务后即使触及模型提交上限，仍可轮询该任务直到完成。对于经网关流式传输的模型服务提供方，这也意味着视频字节经过网关时不计入模型限制，因此应相应规划数据面的出口带宽。

该请求解析到的输入安全护栏，无论关联在模型、调用方 API Key、团队还是环境上，都会在提交前扫描提示词。被阻断的提示词不会创建任何模型服务提供方任务，也不会占用模型限流容量。

端点行为

视频 ID 受模型访问权限约束：API Key 无法访问模型别名的调用方请求该 ID 时会收到 404；未知或格式错误的 ID 也会返回 404。错误类型为 video_not_found。
使用支持的模型服务提供方列表之外的模型别名提交任务时，会返回未实现错误。
如果模型服务提供方密钥的 api_base 以其兼容 OpenAI 或带版本的后缀结尾（Alibaba 使用 /compatible-mode/v1、/api/v1 或 /v1；Zhipu 使用 /api/paas/v4；Volcengine Ark 使用 /api/v3），AISIX 会自动推导服务提供方根路径，因此为聊天流量配置的现有密钥可直接使用。Runway 文档中的 Base URL 是不带路径的主机，OpenAI 则同时接受不带路径的主机和 /v1 Base URL。
OpenAI 是唯一具有内置默认 Base URL 的视频模型服务提供方：未设置 api_base 的 OpenAI 模型会解析到标准 OpenAI API。其他模型服务提供方都要求在密钥上设置 api_base。
每次提交都会以零 Token 记录在用量日志中。基于视频时长的成本核算尚未应用到预算。

支持的模型服务提供方

`provider` 值	模型	交付方式
`alibaba`	Alibaba Model Studio Wan	重定向
`zhipuai`（也接受 `zhipu`）	Zhipu CogVideoX	重定向
`volcengine`	Volcengine Ark Seedance	重定向
`runwayml`（也接受 `runway`）	Runway Gen 系列和由 Runway 托管的 Veo	重定向
`openai`	OpenAI Sora	网关流式传输

后续步骤

你已经通过网关的建模视频接口生成视频。对于 AISIX 尚未建模的模型服务提供方视频 API，请使用模型服务提供方透传；当请求正文指定已配置模型时，模型级限流同样适用。

准备工作​

创建视频生成任务​

轮询任务状态​

下载视频​

限流和安全护栏​

端点行为​

支持的模型服务提供方​

后续步骤​