视频生成

平台视频生成接口的请求格式、异步任务、状态查询和成片获取。

接口状态与兼容边界

接口状态

\n平台视频能力通过 /v1/video/generations（兼容异步接口）与 /v1/videos（OpenAI 兼容入口）提供，均为异步任务模式。素材上传与分类管理见媒资与分类管理，现已正式开放。\n

平台提供部分 Videos 兼容能力，但不代表完整兼容 OpenAI 的全部视频方法、参数和响应字段。当前视频接口只接受 JSON 请求；文件上传、全部参数、所有响应字段和所有模型均不在本页统一承诺范围内。

平台后续会统一创建、查询和成片获取入口：POST /v1/videos、GET /v1/videos/{id}、GET /v1/videos/{id}/content，并使用 queued、in_progress、completed、failed 状态。请求体字段、时长类型、尺寸映射、参考素材输入和下载行为，以实际发布版本为准。

素材上传、管理与分类见媒资与分类管理：POST /v1/media 上传、GET /v1/media 列表、DELETE /v1/media/{id} 删除，配套按用户隔离的分类接口；上传返回的 URL 可直接作为参考图填入本文的 image_url。

参数语义速查（Seedance 2.0 / 2.5 / Wan Prime 通用）

如何指定模式

不需要选模式字段——由 content 里的素材组合自动决定：

content 组合	自动进入的模式
只有文本	文生视频
1 张图	图生视频（首帧）
恰好 2 张图	首尾帧生视频（顺序即首→尾）
>2 张图，或含视频/音频	全模态参考生视频

参考图/参考视频先经 POST /v1/media 上传取回公网 URL（见媒资与分类管理），再填入 content。注意：平台素材库仅支持图片与视频上传；audio_url 需要自备公网可访问的音频地址（如自己的 OSS/CDN 链接）。

各字段语义与边界

字段	生效值	越界/非法行为
`parameters.aspect_ratio`	`16:9`（默认）/ `9:16` / `4:3` / `3:4` / `1:1` / `adaptive`（仅 wan3.0 系）	非法值静默回退 16:9，不报错
`parameters.resolution`	`720P` / `1080P`（全部）；`480P` 仅 wan3.0 系	480P 对 Seedance 等直接报错；未知值回退 720P
`parameters.duration`	整数秒；seedance-2-5/wan3.0 系 4-30，其余 4-15	无 -1 智能时长语义：低于 4 按默认 5 秒，高于上限截断到上限（静默）
`parameters.audio`	布尔，模型需支持	不支持的模型忽略
`parameters.watermark`	布尔，默认 false	—
`parameters.prompt_extend`	布尔，默认 true	—
`parameters.n`	≥1，多输出条数	超上限按上游限制处理
`parameters.notify_url`	公网 http/https 回调，≤1024 字节	非法协议/超长提交时报错
其它未知字段	—	忽略，不报错

参考素材上限（上游校验，超出会被生成任务拒绝）

Seedance 2.5：图 30 张 + 视频 10 段 + 音频 10 段；Seedance 2.0/Lite：图 9 + 视频 3 + 音频 3
wan3.0-video(-prime)：图 10 + 视频 5 + 音频 5
参考视频/音频单段 ≤15 秒；参考图单张 ≤30MB、参考视频 ≤200MB（平台素材库口径）

状态查询响应（真实字段）

任务终态后 GET /v1/video/generations/{id} 返回：

{
  "id": "ag_423b3210936a4d348...",
  "object": "video.generation",
  "status": "SUCCEEDED",
  "model": "doubao-seedance-2-5-260628",
  "video_url": "https://yike-output.oss-cn-shanghai.aliyuncs.com/...",
  "video_urls": ["https://yike-output.oss-cn-shanghai.aliyuncs.com/..."],
  "resolution": "720p",
  "duration_seconds": 15,
  "unit_price": 0.988,
  "cost": 19.76,
  "billed": true
}

id 即平台任务 ID，同时也是上游任务 ID（ag_ 前缀，上游永久可查）
duration_seconds：上游实际生成时长（可能与请求值不同——钳制规则见上表）
unit_price：该任务计价单价（按秒模型为元/秒；按张模型为元/张）
cost：实际结算金额（元），含用户组折扣
billed：是否已完成结算（首次查询到 SUCCEEDED 时同步结算）
FAILED 时附带 error 对象与 error_message

Yike 系成片地址为上游直通签名地址（约 6 小时时效，请及时下载）。

各模型参数与能力差异（重点）

不同模型来自不同上游，能力与参数取值差异很大。同一份请求体换一个 model 字段就可能被拒绝或静默降级，请按目标模型核对下表后再提交。

能力矩阵

模型	分辨率	时长	首尾帧	参考素材上限	音频
`doubao-seedance-2-5-260628`	720P / 1080P	4-30 秒	支持	图 30 张 + 视频 10 段 + 音频 10 段（支持仅音频输入）	有声生成
`doubao-seedance-2-0-260128`	720P / 1080P	4-15 秒	支持	图 9 张 + 视频 3 段 + 音频 3 段	有声生成
`seedance-2.0-lite`	720P / 1080P	4-15 秒	支持	图 9 张 + 视频 3 段	可选
`wan3.0-video`	480P / 720P / 1080P	4-30 秒	支持	图 10 张 + 视频 5 段 + 音频 5 段（参考生视频）	支持开关
`wan3.0-video-prime`	480P / 720P / 1080P	4-30 秒	支持	图 10 张 + 视频 5 段 + 音频 5 段（参考生视频）	支持开关
`wan2.7`	720P / 1080P	2-15 秒	支持	单张首帧或首尾帧两图 + 视频续接	音频同步
`happyhorse-1.1`	720P / 1080P	3-15 秒	支持	参考图 4 张	—
`minimax-h3` / `minimax-h3-fast`	768P / 2K	4-15 秒（整数）	支持	图 9 张 + 视频 3 段 + 音频 3 段	可生成声轨

平台侧输入解析规则（所有 Yike 系视频模型统一）

content 数组支持的 type：text、image_url、video_url、audio_url（均使用 { "url": "..." } 形态，URL 需公网可访问——素材上传接口返回的地址可直接使用）。
平台按素材组合自动判定任务类型：
- 仅 1 张图 → 图生视频（首帧）
- 恰好 2 张图 → 首尾帧生视频
- 超过 2 张图，或含视频/音频 → 参考生视频（多模态）
- 无素材 → 纯文生视频
参考素材的数量/时长上限由上游模型校验：超出矩阵上限会被生成任务拒绝。参考视频与音频单段不超过 15 秒。
parameters.resolution：取值按矩阵；480P 仅 wan3.0 系支持，Seedance 系及其它模型传 480p 会被拒绝（不是降级）；平台视频档位目前只有 480P / 720P / 1080P，无 4K。
parameters.duration：按矩阵范围钳制，越界按模型上限截断（如 lite 传 30 秒按 15 秒生成）。
parameters.audio：布尔；仅矩阵标注"有声/可选/开关"的模型生效。
parameters.watermark：布尔，默认 false（不叠加"AI 生成"水印）。
parameters.prompt_extend：布尔，默认 true（上游智能改写提示词），追求严格遵循原文时可关闭。
parameters.notify_url：任务终态回调地址（见媒资与分类管理）。

分辨率/时长被静默处理的两类情况

时长越界：低于 4 秒按 5 秒生成；高于模型上限按上限截断。想要长视频必须选 4-30 秒档的模型（seedance-2-5 / wan3.0 系）。
分辨率未知值：回退 720P。已知但不支持的档位（如给 wan2.7 传 480p）直接返回错误。

每模型最小示例

Seedance 2.5（全模态参考，30 图上限）：

curl -X POST https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {"type": "text", "text": "参考这些图片中的主角，在城市夜景奔跑"},
      {"type": "image_url", "image_url": {"url": "https://api.gfw.net/uploads/materials/<uid>/<md5>.png"}},
      {"type": "video_url", "video_url": {"url": "https://api.gfw.net/uploads/materials/<uid>/<md5>.mp4"}},
      {"type": "audio_url", "audio_url": {"url": "https://api.gfw.net/uploads/materials/<uid>/<md5>.mp3"}}
    ],
    "parameters": {"resolution": "1080P", "duration": 20, "audio": true}
  }'

wan2.7 首尾帧（恰好两张图）：

curl -X POST https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7",
    "content": [
      {"type": "text", "text": "从日出平滑过渡到日落"},
      {"type": "image_url", "image_url": {"url": "<首帧图 url>"}},
      {"type": "image_url", "image_url": {"url": "<尾帧图 url>"}}
    ],
    "parameters": {"resolution": "1080P", "duration": 10}
  }'

wan3.0 参考生视频（480P 可用、4-30 秒）：

curl -X POST https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "content": [
      {"type": "text", "text": "参考这段视频的运镜风格"},
      {"type": "video_url", "video_url": {"url": "<参考视频素材 url>"}}
    ],
    "parameters": {"resolution": "480P", "duration": 15, "audio": false}
  }'

异步流程与接口选择

视频生成需要先创建任务，再轮询状态，完成后获取成片。创建成功不等于视频完成，不能把任务 ID 当作播放地址。不要将视频模型放入 Chat Completions、Responses 或 Messages 的文本模板。

当前提供两种平台视频调用形式：Videos 兼容入口 /v1/videos，以及兼容异步入口 /v1/video/generations。两者的请求字段、状态值和成片获取方式不同，不能只替换 URL 而保留同一请求体。

兼容异步接口创建时返回 PENDING；Videos 兼容接口将待处理任务表示为 queued 或 in_progress。轮询时应按所使用的接口识别状态，不能见到 PENDING 就尝试下载。

端点与鉴权

操作	Videos 兼容接口	兼容异步接口
创建任务	`POST /v1/videos`	`POST /v1/video/generations`
查询任务	`GET /v1/videos/{id}`	`GET /v1/video/generations/{id}`
获取成片	`GET /v1/videos/{id}/content` 返回二进制	完成后读取 `video_url` 或 `video_urls`
常见终态	`completed` / `failed`	`SUCCEEDED` / `FAILED`

完整地址统一以 https://api.gfw.net 开头。创建、状态查询和标准 content 请求使用 Authorization: Bearer $GFW_API_KEY。下载媒体地址时不要附带平台 API Key。

/v1/videos 并非所有平台视频模型都可用。若接口提示使用 /v1/video/generations，应按兼容格式重新设计请求，而不是只重复提交。

Videos 兼容入口只接受 application/json 请求体；seconds 必须是 JSON number，例如 5，不能写成字符串。该入口不支持 multipart/form-data、curl -F 或通过 input_reference 上传文件。

请求参数与计价单位

字段	接口	类型	说明
`model`	两者	string	必填，使用平台模型 ID
`prompt`	Videos 兼容接口	string	文生视频提示
`seconds`	Videos 兼容接口	number	请求时长，支持范围由模型决定
`size`	Videos 兼容接口	string	分辨率或宽高，支持值由模型决定
`content`	兼容异步接口	array	内容列表，文本示例为 `{\"type\":\"text\",\"text\":\"...\"}`
`parameters`	兼容异步接口	object	参数对象，可包含 `resolution`、`duration`、`audio`
`parameters.resolution`	兼容异步接口	string	例如 `720p`，支持值由模型决定
`parameters.duration`	兼容异步接口	integer	请求时长，模型可能有不同限制
`parameters.audio`	兼容异步接口	boolean	是否生成音频，模型需支持

图生视频、参考视频、编辑等能力需要相应模型支持，不能把一个模型的输入方式推广到所有模型。本页只展示文生视频。

视频价格可能按秒或按次计量，平台依据模型价格规则、分辨率和音频选项计算。以模型价格、计费与充值和用量记录为准，不按文本 Token 单价计算视频。

Videos 兼容接口示例

设置 GFW_API_KEY 和 GFW_VIDEO_MODEL，后者必须是已确认支持 Videos 兼容接口的真实平台模型 ID。本文示例不会替你提交任务。

set -eu
: "${GFW_API_KEY:?请先设置 GFW_API_KEY}"
: "${GFW_VIDEO_MODEL:?请设置平台视频模型 ID}"
payload=$(python -c 'import json,os; print(json.dumps({"model":os.environ["GFW_VIDEO_MODEL"],"prompt":"日落下的海滩，固定镜头，缓慢的海浪。","size":"1344x768","seconds":5},ensure_ascii=False))')
created=$(curl --fail-with-body --silent --show-error --max-time 60 \
  https://api.gfw.net/v1/videos \
  -H "Authorization: Bearer $GFW_API_KEY" \
  -H 'Content-Type: application/json' --data "$payload")
task_id=$(printf '%s' "$created" | python -c 'import json,sys; d=json.load(sys.stdin); assert d.get("code",0)==0 and not d.get("error"),d; print(d["id"])')
printf '任务 ID：%s\n' "$task_id"

查询任务：

curl --fail-with-body --silent --show-error \
  "https://api.gfw.net/v1/videos/${task_id}" \
  -H "Authorization: Bearer $GFW_API_KEY"

完成后获取成片：

curl --fail-with-body --silent --show-error --max-time 120 \
  "https://api.gfw.net/v1/videos/${task_id}/content" \
  -H "Authorization: Bearer $GFW_API_KEY" --output video.mp4

兼容异步接口示例

使用平台模型 ID 和兼容请求格式：

set -eu
: "${GFW_API_KEY:?请先设置 GFW_API_KEY}"
: "${GFW_VIDEO_MODEL:?请设置平台视频模型 ID}"
created=$(curl --fail-with-body --silent --show-error --max-time 60 \
  https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"model\":\"$GFW_VIDEO_MODEL\",\"content\":[{\"type\":\"text\",\"text\":\"日落下的海滩，固定镜头，缓慢的海浪。\"}],\"parameters\":{\"resolution\":\"720p\",\"duration\":5,\"audio\":false}}")
task_id=$(printf '%s' "$created" | python -c 'import json,sys; print(json.load(sys.stdin)["id"])')
printf '任务 ID：%s\n' "$task_id"

完成后从响应读取 video_url 或 video_urls，再下载媒体文件。下载时不要把平台 API Key 附加到媒体地址。

任务响应字段

下面均为结构示意，ID 和地址不是实际生成结果。

{"id":"vid_example","object":"video.generation","model":"platform-video-model","status":"completed","usage":{"duration_seconds":5}}

兼容异步接口：

{"id":"task_example","object":"video.generation","model":"platform-video-model","status":"SUCCEEDED","video_url":"https://api.gfw.net/media/videos/example.mp4"}

标准成片由 /content 下载。兼容成片使用 video_url 或 video_urls；如果已完成但地址尚空，可在同一截止时间内继续查询。查询也可能直接返回 HTTP 错误，不能只等 JSON 状态。

超时、文件与相关文档

300 秒是示例的轮询预算，不是服务生成时限或完成保证。轮询超时不会取消后台任务；保存任务 ID，稍后查询，避免重复提交造成多次生成。

完成后及时下载并验证媒体文件，不能把临时访问地址当作长期存储。生产下载还应设置文件大小限制、整体截止时间和安全的地址访问策略。成功获得视频不代表账单结算已验证；核对费用请查看计费与充值。

相关文档：图片生成、模型与能力、用量与调用日志、错误码与重试。

接口状态与兼容边界复制章节链接

参数语义速查（Seedance 2.0 / 2.5 / Wan Prime 通用）复制章节链接

如何指定模式复制章节链接

各字段语义与边界复制章节链接

参考素材上限（上游校验，超出会被生成任务拒绝）复制章节链接

状态查询响应（真实字段）复制章节链接

各模型参数与能力差异（重点）复制章节链接

能力矩阵复制章节链接

平台侧输入解析规则（所有 Yike 系视频模型统一）复制章节链接

分辨率/时长被静默处理的两类情况复制章节链接

每模型最小示例复制章节链接

异步流程与接口选择复制章节链接

端点与鉴权复制章节链接

请求参数与计价单位复制章节链接

Videos 兼容接口示例复制章节链接

兼容异步接口示例复制章节链接

任务响应字段复制章节链接

超时、文件与相关文档复制章节链接

本页目录