版本：Dev

视频生成

视频生成功能允许应用通过 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",
  "model_name": "wan2.7-t2v",
  "provider_key_id": "YOUR_PROVIDER_KEY_ID"
}

导出网关连接和请求值：

# AISIX_PROXY 不含尾部斜杠或 /v1 等端点路径
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="wan-video-prod"

创建视频生成任务

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

curl -sS -X POST "${AISIX_PROXY}/v1/videos" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "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，并将其原样传给状态和下载路由。它包含经编码的路由信息，不是 Secret 或授权凭据。检索时仍需要一个可访问该模型的调用方 API Key。

请求字段：

字段	必填	含义
`model`	是	AISIX 模型别名。
`prompt`	是	用于生成视频的文本提示词。
`seconds`	否	视频时长（秒），可以是整数或数字字符串。转发为各模型服务提供方自己的时长参数，参见参数映射。
`size`	否	像素尺寸，格式为 `WIDTHxHEIGHT`，例如 `1280x720`。各模型服务提供方表达输出尺寸的方式不同，并会按其各模型的取值列表校验该值，因此设置前请查阅参数映射和该模型服务提供方的模型文档。

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

轮询任务状态

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

curl -sS "${AISIX_PROXY}/v1/videos/YOUR_VIDEO_ID" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

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

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

status 是包含四个值的枚举：

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

AISIX 会把各模型服务提供方自己的任务状态归一化到该枚举。有些模型服务提供方没有单独的排队状态，其任务提交后直接进入 in_progress：

`provider` 值	`queued`	`in_progress`	`completed`	`failed`
`alibaba`	`PENDING`	`RUNNING`	`SUCCEEDED`	`FAILED`、`CANCELED`、`UNKNOWN` 或其他状态
`zhipuai`	不返回，任务直接从 `in_progress` 开始	`PROCESSING`	`SUCCESS`	`FAIL` 或其他状态
`volcengine`	`queued`	`running`	`succeeded`	`failed`、`cancelled`、`expired` 或其他状态
`runwayml`	`PENDING`、`THROTTLED`	`RUNNING`	`SUCCEEDED`	`FAILED`、`CANCELLED` 或其他状态
`openai`	`queued`	`in_progress`	`completed`	`failed` 或其他状态

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

下载视频

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

curl -sS -L -o video.mp4 \
  "${AISIX_PROXY}/v1/videos/YOUR_VIDEO_ID/content" \
  -H "Authorization: Bearer ${AISIX_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" \
  "${AISIX_PROXY}/v1/videos/YOUR_VIDEO_ID/content" \
  -H "Authorization: Bearer ${AISIX_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 各层级的容量。任务轮询特意不受模型级限制：客户端提交任务后即使触及模型提交上限，仍可轮询该任务直到完成。对于经网关流式传输的模型服务提供方，这也意味着视频字节经过网关时不计入模型限制，因此应相应规划网关的出口带宽。

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

端点行为

如果模型服务提供方密钥的 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。
提交路由要求 JSON 媒体类型，例如 application/json。OpenAI Python SDK 中的视频创建方法每次调用都会发送 multipart/form-data，即使没有参考素材也一样，因此无法驱动该路由，请改用普通 HTTP 客户端提交。两条 GET 路由是普通 GET 请求，不受此限制。
OpenAI 是唯一具有内置默认 Base URL 的视频模型服务提供方：未设置 api_base 的 OpenAI 模型会解析到标准 OpenAI API。其他模型服务提供方都要求在密钥上设置 api_base。
每次到达模型服务提供方的提交都会以零 Token 记录在用量日志中。模型服务提供方不在允许列表内的提交同样会被记录，状态为 501，零 Token。在分发前就被拒绝的请求（例如 JSON 格式错误）不会产生用量记录。基于视频时长的成本核算尚未应用到 AISIX Cloud 预算。
提交不保证至多一次。AISIX 会重试发送阶段的传输失败和上游 5xx，而首次尝试是否已到达模型服务提供方是无法确知的，因此重试可能创建第二个计费任务，且调用方永远看不到它的 ID。上游已经响应、只是响应正文读取或解析失败时，AISIX 特意不重试。

支持的模型服务提供方

AISIX 按模型别名自身的 provider 值分发视频路由，而不是按上游模型名称；别名关联的密钥只提供凭证和 api_base。这些路由接受直连别名和多目标模型，后者的每个目标都必须是下表中的服务提供方。合议模型或语义路由别名会返回 400。

AISIX 不维护模型 ID 允许列表，只会把别名中配置的上游模型名称按下表的固定映射转发出去，因此能否生成成功仍取决于该模型是否接受转发后的请求形态。创建别名前请查阅该模型服务提供方的最新模型列表以及该模型自身的参数规则。

`provider` 值	配置指南	视频模型	交付方式
`alibaba`	Qwen（阿里云）	Model Studio Wan 和 HappyHorse 文生视频，例如 `wan2.7-t2v`、`wan2.2-t2v-plus` 和 `happyhorse-1.1-t2v`	重定向
`zhipuai`（也接受 `zhipu`）	Zhipu AI	CogVideoX，例如 `cogvideox-3`	重定向
`volcengine`	Volcengine Ark	Ark Seedance，例如 `doubao-seedance-2-0-260128`	重定向
`runwayml`（也接受 `runway`）	RunwayML	文生视频端点上的 Runway Gen 系列和由 Runway 托管的模型，例如 `gen4.5`、`veo3.1` 和 `seedance2`	重定向
`openai`	OpenAI	Sora：`sora-2` 和 `sora-2-pro`	网关流式传输

警告

OpenAI 已于 2026 年 3 月 24 日弃用 Videos API 和 Sora 2 系列模型，并将于 2026 年 9 月 24 日将其从 API 中移除。届时以 sora-2 或 sora-2-pro 为上游的别名将停止工作。

模型别名的模型服务提供方不在上表中时，提交会返回 501 not_implemented。此时请通过透传路由访问其原生视频 API。

有两个可用于聊天流量的 provider 值被特意排除在外：alibaba-cn 和 zai。它们访问的 API 根路径与各自支持视频的对应值不同，因此视频别名必须使用 alibaba 或 zhipuai。

参数映射

AISIX 会把统一请求中的 seconds 和 size 映射到各模型服务提供方自己的参数上。该映射按模型服务提供方划分，而非按模型：AISIX 不会判断别名指向哪个模型系列，因此当某个模型服务提供方的新模型改用了别的参数时，省略统一字段是调用方自己的责任。模型服务提供方完全无法表达的字段会被丢弃，而不会被改写成语义不同的另一个参数；模型服务提供方会按其各模型的取值列表校验收到的值。

`provider` 值	`seconds` 映射为	`size` 映射为
`alibaba`	`parameters.duration`	`parameters.size`，格式为 `WIDTH*HEIGHT`。该参数对应 Wan 2.6 及更早版本的请求协议。Wan 2.7 模型已改用 `resolution` 和 `ratio` 档位，而 AISIX 仍会原样转发你发送的值，因此 Wan 2.7 别名请自行省略 `size`，由模型服务提供方使用默认值。
`zhipuai`	`duration`	`size`，格式为 `WIDTHxHEIGHT`，原样转发
`volcengine`	`duration`	不转发。Ark 使用 `resolution` 和 `ratio` 档位表达输出尺寸，无法承载任意 `WIDTHxHEIGHT`。AISIX 会校验格式后丢弃该值，由模型服务提供方使用默认值。提交响应仍会回显你发送的 `size`，但这并不代表 Ark 使用了它；轮询响应不返回该字段。
`runwayml`	`duration`	`ratio`，格式为 `WIDTH:HEIGHT`。AISIX 只替换分隔符，具体取值由 Runway 按其各模型的分辨率列表校验。
`openai`	`seconds`，以字符串形式发送。OpenAI 的视频创建 schema 接受 `4`、`8` 或 `12`。	`size`，格式为 `WIDTHxHEIGHT`，原样转发。schema 列出 `720x1280`、`1280x720`、`1024x1792` 和 `1792x1024`，但 OpenAI 各模型页面公布的取值范围更窄，请查阅对应模型页面。AISIX 只校验 `WIDTHxHEIGHT` 格式。

路由未建模的请求字段

这些路由只覆盖文生视频。除 model、prompt、seconds 和 size 之外的字段会被忽略而不是拒绝，因此携带这些字段的请求仍会生成视频，但只依据提示词生成。

input_reference 会被忽略。这些路由未建模图生视频和视频生视频。
模型服务提供方原生的生成控制参数，例如负向提示词、随机种子、参考图，或 Wan 2.7 的 resolution 和 ratio 档位，都没有对应的统一字段，不会被转发。
AISIX 只提供 POST /v1/videos、GET /v1/videos/{video_id} 和 GET /v1/videos/{video_id}/content 三条建模视频路由。模型服务提供方用于列出、删除、混剪、编辑或延长视频的路由均未建模，生成之外的其他模型服务提供方专有路由同样未建模。

调用方需要上述任一能力时，请配置透传路由：它直达模型服务提供方的原生视频 API，同时仍由网关持有凭证并执行调用方 API Key 的访问规则。

错误

下表列出的是 AISIX 自身产生的状态码。模型服务提供方返回的 4xx 会保留其状态码，以上游错误封装转发；模型服务提供方的 5xx、传输失败，或 AISIX 无法解析的响应会转为 502；上游超时转为 504；请求正文超过大小上限转为 413。

下载失败的表现取决于交付方式。网关流式传输时，AISIX 会在开始传输前检查模型服务提供方的内容端点，因此该端点返回的错误是 JSON 错误封装；而响应头发出之后被中断的流不是，此时若模型服务提供方声明了 Content-Length，调用方看到的是长度不足。重定向交付时，AISIX 从不获取文件：它只把模型服务提供方给出的绝对 http 或 https URL 原样返回、不做校验，因此客户端跟随重定向之后的任何失败都来自模型服务提供方或其 CDN，格式也由对方决定。

状态码	触发场景
`400`	请求格式错误：`seconds` 不是正整数，或 `size` 不是 `WIDTHxHEIGHT`。此外，任务仍在进行时内容路由返回 `400` 并提示调用方继续轮询；任务失败时返回 `400` 和模型服务提供方的失败详情。
`401`	调用方 API Key 缺失或无效。
`403`	提交时调用方 API Key 无权使用该模型别名，或请求来自模型允许列表之外的客户端 IP。错误类型为 `permission_denied`；IP 被拒时还会携带 `ip_restricted` 错误码。
`404`	提交时 `model` 未匹配到网关已知的任何别名，错误类型为 `model_not_found`。GET 路由上则是视频 ID 未知或格式错误，或该 ID 属于调用方 API Key 无法访问的模型，错误类型为 `video_not_found`。GET 路由会把访问被拒和未实现的模型服务提供方一并折叠为 `404`，因此无法用 ID 探测有哪些模型存在。
`422`	输入安全护栏阻断了提示词。此时不会创建模型服务提供方任务，也不会占用限流容量。
`429`	请求被限流或 AISIX Cloud 预算拒绝。提交同时计入调用方 API Key 各层级和模型限制；状态和内容调用只计入调用方 API Key 各层级。AISIX Cloud 会在三条路由上检查调用方预算，因此超预算的调用方无法轮询或下载自己已付费提交的任务。
`501`	模型别名解析到的模型服务提供方不在视频路由的允许列表内。错误类型为 `not_implemented`。

模型服务提供方报告任务失败时，状态路由不会返回 HTTP 错误：GET /v1/videos/{video_id} 返回 200，其中 "status": "failed"，并带有承载模型服务提供方 code 和 message 的 error 对象。

后续步骤

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

准备工作​

创建视频生成任务​

轮询任务状态​

下载视频​

限流和安全护栏​

端点行为​

支持的模型服务提供方​

参数映射​

路由未建模的请求字段​

错误​

后续步骤​