> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 视频（OpenAI）

> 通过 OpenAI 风格 /v1/videos 接口调用火山方舟 Doubao Seedance 视频模型，统一使用 video_ 前缀任务 ID。

本页介绍如何在 HingNet AI 中，使用 **OpenAI 风格的视频接口** `/v1/videos` 调用火山方舟 Doubao Seedance 视频模型，并与官方 Sora/Veo 接口保持一致的体验：

* 统一的请求体：`model` / `prompt` / `seconds` / `size` / `input_reference`；
* 统一的任务 ID：响应中的 `id` 均为 `video_<PlatformTaskID>` 形式；
* 统一的查询方式：`GET /v1/videos/{id}`。

> 对比关系：
>
> * 原生 Ark 接口：`POST /volcark/api/v3/contents/generations/tasks`（见 `doubao/video` 文档）
> * OpenAI 风格接口（本页）：`POST /v1/videos`

## 1. 前置条件

```bash theme={null}
export BASE_URL="https://models.hingnet.com.cn/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

HTTP 头部：

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

控制台需要将以下模型名映射到 VolcArk Doubao Seedance 渠道：

* `doubao-seedance-1-5-pro`
* `doubao-seedance-1-0-pro`
* `doubao-seedance-1-0-pro-fast`
* `doubao-seedance-1-0-lite-t2v`
* `doubao-seedance-1-0-lite-i2v`

## 2. OpenAI 风格接口概览

在 OpenAI 风格模式下，你只需要关注统一的 `/v1/videos` 接口：

* 创建任务：`POST /v1/videos`
* 查询任务：`GET  /v1/videos/{id}`
* 下载内容：`GET  /v1/videos/{id}/content`

> **VolcArk 字段兼容**
>
> * Doubao Seedance 模型在 `/v1/videos` 下支持 Ark 官方字段：`duration`、`ratio`、`resolution`、`watermark`、`generate_audio`、`camera_fixed`；
> * `duration` 会作为 `seconds` 的别名处理；
> * 若渠道配置 `plugin.doubao_video.vendor = "chrisapi"`，上述字段会自动转换为 prompt 参数提交到上游。

> **Seedance 参数约束（2026-02-11）**
>
> * 支持模型：`doubao-seedance-1-5-pro`、`doubao-seedance-1-0-pro`、`doubao-seedance-1-0-pro-fast`；
> * `seconds`：`1-5-pro` 支持 `4-12`，`1-0-pro / 1-0-pro-fast` 支持 `2-12`；
> * `input_reference`：`1-5-pro / 1-0-pro` 最多 2 张；`1-0-pro-fast` 最多 1 张；
> * `generate_audio`：仅 `1-5-pro` 支持；
> * `resolution`：`1-5-pro` 仅支持 `480p/720p`；`1-0-pro / 1-0-pro-fast` 支持 `480p/720p/1080p`。

> **input\_reference 兼容写法**
>
> * 数组：`["https://.../first.png","https://.../last.png"]`
> * 单字符串：`"https://.../only.png"`
> * 字符串化数组：`"[\"https://.../first.png\",\"https://.../last.png\"]"`

## 3. 文生视频示例（T2V）

以 `doubao-seedance-1-0-pro-fast` 为例：

```bash theme={null}
curl -X POST "$BASE_URL/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-fast",
    "prompt": "夜晚城市街道上的车辆灯光流动",
    "seconds": 8,
    "size": "1280x720"
  }'
```

典型成功返回：

```json theme={null}
{
  "id": "video_01KB1Y6FT0QMDKS0Y1YYYSS4D0",
  "object": "video",
  "status": "queued",
  "model": "doubao-seedance-1-0-pro-fast",
  "seconds": 8,
  "size": "1280x720"
}
```

说明：

* `id`：平台生成的全局任务 ID，**始终以 `video_` 开头**；
  * 在 `/panel/task` 页面中你会看到同一个值（列名为「任务ID」）。
* `model`：保留对外暴露的 API 模型名（例如 `doubao-seedance-1-0-pro-fast`）。

## 3.1 ChrisApi 上游（可选）

当渠道配置 `plugin.doubao_video.vendor = "chrisapi"` 时：

* **仅支持模型**：`doubao-seedance-1-5-pro`
* **字段规则**：仍使用 VolcArk 官方字段（`duration`/`ratio`/`resolution` 等）
* **内部转换**：平台将字段追加为 prompt 参数（`-ratio`/`-resolution`/`-watermark`/`-generate_audio`/`-camera_fixed`）

## 4. 图生视频示例（I2V）

图生视频模型通过 `input_reference` 传入参考图 URL（兼容 `input_image` / `input_images`）：

```bash theme={null}
curl -X POST "$BASE_URL/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v",
    "prompt": "一幅油画风格的海边日落场景",
    "seconds": 6,
    "size": "720x1280",
    "input_reference": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_first_frame.png"
    ]
  }'
```

<Callout type="warning">
  对于 I2V 模型（如 <code>doubao-seedance-1-0-lite-i2v</code>），若未提供任何图片引用，平台会返回错误：

  <br />

  <code>image to video models require image in content</code>
</Callout>

## 5. 查询任务状态

创建任务后，可通过 `id` 查询最新状态：

```bash theme={null}
export VIDEO_ID="video_01KB1Y6FT0QMDKS0Y1YYYSS4D0"

curl "$BASE_URL/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"
```

典型返回：

```json theme={null}
{
  "id": "video_01KB1Y6FT0QMDKS0Y1YYYSS4D0",
  "object": "video",
  "status": "completed",
  "model": "doubao-seedance-1-0-pro-fast",
  "seconds": 8,
  "size": "1280x720",
  "video_url": "https://models.hingnet.com.cn/video/01KB1Y6FT0QMDKS0Y1YYYSS4D0.mp4"
}
```

说明：

* `status`：`queued` / `in_progress` / `completed` / `failed` 等；
* `video_url`：
  * 为平台代理后的 URL，不会暴露上游源站域名；
  * 同一 URL 会出现在 `/panel/task` 弹窗中的「平台最终响应」里。
  * 若上游返回中缺失 `video_url`，平台会自动回退请求提取视频地址（仅在已完成态触发）。

## 6. 下载视频内容

下载内容与 Sora/Veo 对齐，使用 `/v1/videos/{id}/content`：

```bash theme={null}
curl -L "$BASE_URL/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  -o doubao-seedance-demo.mp4
```

## 7. 与原生 VolcArk 接口的对比

| 维度      | 原生 VolcArk 接口                                          | OpenAI 风格接口 `/v1/videos`                            |
| ------- | ------------------------------------------------------ | --------------------------------------------------- |
| 创建路径    | `/volcark/api/v3/contents/generations/tasks`           | `/v1/videos`                                        |
| 请求体     | `model + content[{type,text/image_url,...}]`           | `model + prompt + seconds + size + input_reference` |
| 任务 ID   | Ark 的 `id` / `task_id`（不带前缀）                           | 平台全局 ID：`video_<PlatformTaskID>`                    |
| 查询路径    | `/volcark/api/v3/contents/generations/tasks/{task_id}` | `/v1/videos/{id}`                                   |
| 控制台任务列表 | `PlatformTaskID`（原生：裸 ULID；现在：带 `video_` 前缀）           | 同一值，展示为 `video_<PlatformTaskID>`                    |

推荐使用：

* 如希望与 OpenAI Sora/Veo 风格统一，**优先使用本页的 `/v1/videos` 接口**；
* 如需完全对齐火山方舟官方文档（原生字段），可使用 `doubao/video` 文档中的 VolcArk 原生接口。