> ## 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.

# 视频（原生）

> 通过 /volcark/api/v3/contents/generations/tasks 使用 Doubao Seedance 视频模型（含文生视频与图生视频）。

本页介绍如何在 HingNet AI 中，通过 **火山方舟 VolcArk 原生接口** 调用 Doubao Seedance 视频模型，包括：

* 文生视频（T2V）：`doubao-seedance-1-5-pro`、`doubao-seedance-1-0-pro`、`doubao-seedance-1-0-pro-fast`、`doubao-seedance-1-0-lite-t2v`
* 图生视频（I2V）：`doubao-seedance-1-0-lite-i2v`

所有请求都经由 HingNet AI 转发到火山方舟，**不需要自行签名**，只需在 Header 中携带 HingNet AI API Key。

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

统一使用：

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

## 接口总览

在 HingNet AI 中，Doubao Seedance 的 VolcArk 原生接口统一挂载在：

* 提交任务：`POST /volcark/api/v3/contents/generations/tasks`
* 查询任务：`GET  /volcark/api/v3/contents/generations/tasks/{task_id}`
* 列表查询：`GET  /volcark/api/v3/contents/generations/tasks`
* 取消任务：`DELETE /volcark/api/v3/contents/generations/tasks/{task_id}`

你只需要关注上述 HTTP 路径和请求体结构，无需了解内部路由和代码实现细节。

## 请求体结构

创建 Seedance 视频任务时，请求体主体为：

```json theme={null}
{
  "model": "doubao-seedance-1-0-pro",
  "content": [
    { "type": "text", "text": "一个男孩在草地上和小狗玩耍" }
  ]
}
```

重要字段说明：

* `model`：Seedance 模型名称，平台会在内部自动映射为版本化的模型 ID（如 `doubao-seedance-1-5-pro-251215`），但对用户侧保持使用原始 API 模型名。
* `content`：内容数组，支持多段内容。
  * 文生视频（T2V）：至少包含一条 `type: "text"` 的文本。
  * 图生视频（I2V）：必须同时包含文本和图片，其中图片使用 `image_url` 格式。

示例：图生视频（I2V）请求体：

```json theme={null}
{
  "model": "doubao-seedance-1-0-lite-i2v",
  "content": [
    {
      "type": "text",
      "text": "一幅油画风格的海边日落场景"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_first_frame.png"
      }
    }
  ]
}
```

<Callout type="warning">
  对于图生视频模型（I2V，例如 `doubao-seedance-1-0-lite-i2v`），如果 `content` 中未包含图片（`image_url`），火山方舟会返回错误：

  <br />

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

  <br />

  请确保至少传入一张参考图。
</Callout>

常用附加参数（可选）：

* `duration` / `frames`：控制视频时长；若同时指定，以 `frames` 为准；
* `ratio` / `aspect_ratio`：画面宽高比，例如 `16:9`、`9:16`；
* `resolution`：如 `720p`、`1080p`；
* `seed`：随机种子，用于结果可复现；
* 其他官方文档支持的参数也会被透传，平台会根据分辨率与时长自动计算计费用量。

## ChrisApi 上游（可选）

当渠道配置 `plugin.doubao_video.vendor = "chrisapi"` 时，平台会在保持 VolcArk 原生接口不变的前提下，改走 ChrisApi 上游：

* **仅支持模型**：`doubao-seedance-1-5-pro`
* **请求参数**：保持 Ark 官方字段不变（`duration`/`ratio`/`resolution`/`watermark`/`generate_audio`/`camera_fixed`）
* **内部转换**：平台会将上述字段转换为 prompt 参数（`-ratio`/`-resolution`/`-watermark`/`-generate_audio`/`-camera_fixed`）提交到上游

插件示例（chrisapi 自定义上游）：

```json theme={null}
{
  "doubao_video": {
    "vendor": "chrisapi",
    "chris_base_url": "https://chrisapius.top",
    "chris_api_key": "your-chrisapi-key"
  }
}
```

## 文生视频示例（T2V）

以 Pro 模型 `doubao-seedance-1-0-pro` 为例：

```bash theme={null}
curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro",
    "content": [
      { "type": "text", "text": "一个男孩在草地上和小狗玩耍" }
    ],
    "duration": 6,
    "ratio": "16:9",
    "resolution": "720p"
  }'
```

成功时会返回任务 ID。原生 Ark 接口与平台全局视频任务 ID 并存：

```json theme={null}
{
  "id": "cgt-xxxx",
  "platform_id": "video_<PlatformTaskID>"
}
```

其中：

* `id`：火山方舟原生任务 ID（例如 `cgt-2025...`），可直接用于调用 Ark 官方文档中的查询/取消接口；
* `platform_id`：平台全局视频任务 ID，前缀固定为 `video_`，与 `/v1/videos` 接口以及任务中心共用同一套 ID 体系。

平台会在后台记录任务，并根据分辨率/时长自动估算 token 用量，用于计费展示。

## 图生视频示例（I2V）

以 Lite 图生视频模型 `doubao-seedance-1-0-lite-i2v` 为例：

```bash theme={null}
curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v",
    "content": [
      {
        "type": "text",
        "text": "一幅油画风格的海边日落场景"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_first_frame.png"
        }
      }
    ],
    "duration": 5,
    "ratio": "9:16",
    "resolution": "720p"
  }'
```

注意：

* `content` 中图片 URL 支持公网可访问链接；
* 推荐图片宽高比与目标视频一致（例如竖屏 `9:16` 对应竖版参考图）。

## 查询任务状态

创建任务后，可以使用 **Ark 原生 ID** 或 **平台全局 ID** 查询进度：

```bash theme={null}
export TASK_ID="cgt-xxxx"              # Ark 原生任务 ID
# 或使用平台全局视频任务 ID（推荐）：
# export TASK_ID="video_<PlatformTaskID>"

curl "$BASE_URL/volcark/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"
```

典型成功响应（平台会在标准响应基础上附加 `platform_id` 字段）：

```json theme={null}
{
  "id": "cgt-xxxx",
  "platform_id": "video_<PlatformTaskID>",
  "model": "doubao-seedance-1-0-pro-250528",
  "status": "succeeded",
  "content": {
    "video_url": "https://xxx/xxx.mp4",
    "last_frame_url": "https://xxx/last_frame.png",
    "width": 1280,
    "height": 720
  },
  "duration": 6,
  "framespersecond": 16,
  "usage": {
    "video_tokens": 123456
  }
}
```

其中：

* `status`：`queued` / `running` / `succeeded` / `failed` / `cancelled`；
* `content.video_url`：成片地址，由 HingNet AI 在 `/panel/task` 中直接展示；
* `usage.video_tokens`：视频 token 用量，将用于计费。

## 取消任务与列表查询

取消任务：

```bash theme={null}
curl -X DELETE "$BASE_URL/volcark/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"
```

分页查询任务：

```bash theme={null}
curl "$BASE_URL/volcark/api/v3/contents/generations/tasks?page_num=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
```

支持的查询参数包括：

* `page_num` / `page_size`：分页控制；
* `filter.status`：任务状态；
* `filter.task_ids`：指定任务 ID 列表；
* `filter.model`：指定模型，如 `doubao-seedance-1-0-pro`。

## 计费与监控

Seedance 视频的价格已在 `/panel/pricing` 中按模型预设，计费会结合：

* 请求中的时长（`duration` / `frames`）、分辨率等参数；
* 上游返回的 `usage` 字段（若存在）。

你可以在：

* 「调用日志」中查看每次请求的 token 用量与费用；
* 「任务中心 / 视频任务」中查看任务状态、耗时和播放地址。

## 常见问题（FAQ）

### 1. I2V 提示 “image to video models require image in content”

原因是 `model` 为 I2V，但 `content` 中没有图片。请按本页示例增加：

```json theme={null}
{
  "type": "image_url",
  "image_url": { "url": "https://..." }
}
```

### 2. 任务长时间处于 queued/running

* 可以通过 `GET /volcark/api/v3/contents/generations/tasks/{task_id}` 查看 `status` 与 `error` 字段；
* 若持续长时间未结束，可尝试 `DELETE` 取消任务并重新提交；
* 后台会在任务进入终态时自动记录耗时与异常信息，便于排查。

### 3. 如何区分 T2V / I2V 模型？

* 文生视频：`doubao-seedance-1-0-pro`、`doubao-seedance-1-0-pro-fast`、`doubao-seedance-1-0-lite-t2v`
* 图生视频：`doubao-seedance-1-0-lite-i2v`

在业务代码中，可以根据模型名动态决定是否强制要求 `image_url`。