# 视频生成

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

## 接口状态与兼容边界 [#接口状态与兼容边界]


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

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

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

素材上传、管理与分类见[媒资与分类管理](/docs/media-management)：`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 | 是否生成音频，模型需支持 |

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

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

## Videos 兼容接口示例 [#videos-兼容接口示例]

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

```bash
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"
```

查询任务：

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

完成后获取成片：

```bash
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 和兼容请求格式：

```bash
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 和地址不是实际生成结果。

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

兼容异步接口：

```json
{"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，稍后查询，避免重复提交造成多次生成。

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

相关文档：[图片生成](/docs/image-generation)、[模型与能力](/docs/models)、[用量与调用日志](/docs/usage-logs)、[错误码与重试](/docs/errors)。