# 视频生成

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

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


**接口状态**
\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`。



## 参数语义速查（Seedance 2.0 / 2.5 / Wan Prime 通用） [#参数语义速查seedance-20--25--wan-prime-通用]

### 如何指定模式 [#如何指定模式]

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

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

参考图/参考视频先经 `POST /v1/media` 上传取回公网 URL（见[媒资与分类管理](/docs/media-management)），再填入 `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}` 返回：

```json
{
  "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 系视频模型统一） [#平台侧输入解析规则所有-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`：任务终态回调地址（见[媒资与分类管理](/docs/media-management)）。

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

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

### 每模型最小示例 [#每模型最小示例]

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

```bash
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 首尾帧（恰好两张图）：

```bash
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 秒）：

```bash
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 | 是否生成音频，模型需支持 |

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

视频价格可能按秒或按次计量，平台依据模型价格规则、分辨率和音频选项计算。以模型价格、[计费与充值](/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)。