视频生成
平台视频生成接口的请求格式、异步任务、状态查询和成片获取。
接口状态与兼容边界
接口状态
/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。
异步流程与接口选择
视频生成需要先创建任务，再轮询状态，完成后获取成片。创建成功不等于视频完成，不能把任务 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，稍后查询，避免重复提交造成多次生成。
完成后及时下载并验证媒体文件，不能把临时访问地址当作长期存储。生产下载还应设置文件大小限制、整体截止时间和安全的地址访问策略。成功获得视频不代表账单结算已验证；核对费用请查看计费与充值。