# Seedance 视频任务接口文档

对应页面：`/docs/?section=video`

- **Base URL**：`https://tp-api.chinadatapay.com:8000`
- **鉴权**：`Authorization: Bearer <你的 API Key>`
- **模型**：`doubao-seedance-2.0`
- **协议**：异步任务。先创建视频任务，再通过任务 ID 查询状态和结果。

推荐使用官方端点 `/api/v3/contents/generations/tasks`。网关兼容端点 `/v1/video/tasks` 仍可使用。

目录：

1. [创建视频任务](#1-创建视频任务)
2. [查询单个任务](#2-查询单个任务)
3. [查询任务列表](#3-查询任务列表)
4. [真人素材指南](#4-真人素材指南)
5. [上传素材接口（支持AIGC真人）旧](#5-上传素材接口支持aigc真人旧)
6. [查询单个素材接口（支持AIGC真人）旧](#6-查询单个素材接口支持aigc真人旧)
7. [使用素材创建视频](#7-使用素材创建视频)
8. [计费规则](#8-计费规则)

---

## 1. 创建视频任务

Seedance-2.0 视频生成接口，支持通过文本、图片等输入生成视频。

用途：创建 Seedance 视频生成任务。

| 类型 | 方法 | 路径 |
|---|---|---|
| 网关端点 | POST | `https://tp-api.chinadatapay.com:8000/v1/video/tasks` |
| 官方端点（推荐） | POST | `https://tp-api.chinadatapay.com:8000/api/v3/contents/generations/tasks` |

### 请求示例

```bash
curl https://tp-api.chinadatapay.com:8000/v1/video/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {"type": "text", "text": "一只猫在海边奔跑，电影感，夕阳，4k"},
      {"type": "image_url", "image_url": {"url": "https://example.com/input.jpg"}, "role": "reference_image"}
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "720p",
    "execution_expires_after": 3600,
    "watermark": false
  }'
```

### 主要请求字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 视频生成模型 ID，例如 doubao-seedance-2.0 |
| `content` | array | 是 | 输入内容数组，支持文本、图片、视频、音频、样片任务 ID |
| `callback_url` | string | 否 | 任务回调地址 |
| `return_last_frame` | bool | 否 | 是否返回尾帧 |
| `generate_audio` | bool | 否 | 是否生成同步音频 |
| `draft` | bool | 否 | 是否开启样片模式 |
| `tools` | array/object | 否 | 工具配置 |
| `safety_identifier` | string | 否 | 终端用户唯一标识 |
| `execution_expires_after` | int | 否 | 任务过期时间（秒） |
| `resolution` | string | 否 | 视频分辨率，如 720p、1080p |
| `ratio` | string | 否 | 宽高比，如 16:9、9:16 |
| `duration` | int | 否 | 视频时长（秒） |
| `seed` | int | 否 | 随机种子 |
| `watermark` | bool | 否 | 是否带水印 |

### content 结构

content 支持以下条目类型：

- `text` - 文本
- `image_url` - 图片
- `video_url` - 视频
- `audio_url` - 音频

并支持 role，例如：

- `reference_image` - 参考图片
- `reference_video` - 参考视频
- `reference_audio` - 参考音频

### 响应示例

```json
{ "id": "task_xxxxxx" }
```

---

## 2. 查询单个任务

用途：查询单个视频生成任务详情。

| 类型 | 方法 | 路径 |
|---|---|---|
| 网关端点 | GET | `https://tp-api.chinadatapay.com:8000/v1/video/tasks/{id}` |
| 官方端点（推荐） | GET | `https://tp-api.chinadatapay.com:8000/api/v3/contents/generations/tasks/{id}` |

### Headers

```http
Content-Type: application/json
Authorization: Bearer $API_KEY
```

### 路径参数

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 视频生成任务 ID |

### CURL 示例

```bash
curl https://tp-api.chinadatapay.com:8000/v1/video/tasks/task_xxxxxx \
  -H "Authorization: Bearer sk-xxxxxx"
```

### 状态说明

- `queued`：排队中
- `running`：运行中
- `cancelled`：已取消
- `succeeded`：成功
- `failed`：失败
- `expired`：超时

### 响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 任务 ID |
| `model` | string | 任务使用的模型名和版本 |
| `status` | string | 任务状态 |
| `error` | object | 错误信息，失败时返回 |
| `created_at` | int64 | 创建时间 |
| `updated_at` | int64 | 状态更新时间 |
| `content` | object | 输出内容，通常包含 video_url |
| `seed` | int | 种子 |
| `resolution` | string | 分辨率 |
| `ratio` | string | 宽高比 |
| `duration` | string/int | 时长 |
| `framespersecond` | int | 帧率 |
| `generate_audio` | bool | 是否同步生成音频 |
| `tools` | object | 实际使用工具 |
| `safety_identifier` | string | 安全标识符 |
| `draft` | bool | 是否为 Draft 视频 |
| `draft_task_id` | string | Draft 任务 ID |
| `execution_expires_after` | int | 任务超时时间 |
| `usage` | object | token 用量 |

### 成功响应示例

```json
{
  "id": "cgt-2026xxxxxx",
  "model": "doubao-seedance-2.0",
  "status": "succeeded",
  "error": null,
  "created_at": 1718049470,
  "updated_at": 1718049870,
  "content": {
    "video_url": "https://example.com/video.mp4"
  },
  "seed": 12345,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 4,
  "framespersecond": 24,
  "generate_audio": false,
  "tools": {},
  "safety_identifier": "",
  "draft": false,
  "draft_task_id": "",
  "execution_expires_after": 3600,
  "usage": {
    "completion_tokens": 35800,
    "total_tokens": 35800
  }
}
```

### 失败响应示例

```json
{
  "id": "cgt-2026xxxxxx",
  "model": "doubao-seedance-2.0",
  "status": "failed",
  "error": {
    "code": "OutputVideoSensitiveContentDetected",
    "message": "The request failed because the output video may contain sensitive information. Request ID: {id}"
  },
  "created_at": 1718049470,
  "updated_at": 1718049870
}
```

---

## 3. 查询任务列表

用途：查询视频生成任务列表。

| 类型 | 方法 | 路径 |
|---|---|---|
| 网关端点 | GET | `https://tp-api.chinadatapay.com:8000/v1/video/tasks` |
| 官方端点（推荐） | GET | `https://tp-api.chinadatapay.com:8000/api/v3/contents/generations/tasks` |

### CURL 示例

```bash
curl https://tp-api.chinadatapay.com:8000/v1/video/tasks \
  -H "Authorization: Bearer sk-xxxxxx"
```

---

## 4. 真人素材指南

**base_url**

```text
https://tp-api.chinadatapay.com:8000/seedance-gateway
```

私域真人素材库用于将已授权的真人形象入库，再通过 Seedance 2.0 使用 `asset://asset_id` 作为可信素材生成视频。真人素材需要先完成 H5 真人认证，每个 `Asset Group` 唯一绑定一个真实人物。

**鉴权说明：** 火山方舟真人认证、Asset Group 和 Asset 管理接口使用火山 Access Key / Secret Key 签名鉴权；TopenRouter 创建视频任务接口继续使用 `Authorization: Bearer YOUR_API_KEY`。

### 接入流程

1. 生成认证链接：`CreateVisualValidateSession` — 生成 H5 真人认证页，终端用户完成活体认证后回跳 CallbackURL。
2. 获取 GroupId：`GetVisualValidateResult` — 认证通过后，使用 BytedToken 获取本次创建的素材组 ID。
3. 上传真人素材：`CreateAsset` — 向指定 GroupId 上传图片、视频或音频素材，返回 asset_id。
4. 等待素材可用：`GetAsset` — 轮询素材状态；Status=Active 后可用于视频生成，Failed 表示入库失败。
5. 创建视频任务：`POST /v1/video/tasks` — 在 content[].image_url.url 中传入 asset://asset_id 创建视频。

### 关键规则

- 每个 `Asset Group` 只绑定一个真人，新增妆造可继续上传到同一个素材组。
- 上传素材会与真人认证采集的基准图做面部一致性比对；非同一人物或多人脸素材可能无法入库。
- 素材库按 `ProjectName` 隔离，素材和推理接入点需要在同一项目内，默认项目为 `default`。
- `BytedToken` 用于查询真人认证结果，有效期为 30 分钟。
- `GetAsset` / `ListAssets` 返回的临时 `URL` 通常 12 小时过期，生成视频时应使用 `asset://asset_id`。

### CallbackURL 回跳参数

| 字段 | 说明 |
|---|---|
| `bytedToken` | 本次认证凭证，用于调用 `GetVisualValidateResult` 查询 `GroupId`。 |
| `resultCode` | `10000` 表示真人认证通过；失败后 H5 链接失效，需要重新创建认证会话。 |
| `algorithmBaseRespCode` | 服务端子错误码，认证失败时可用于定位错误类型。 |
| `reqMeasureInfoValue` | 本次操作是否计费，`0` 为不计费，`1` 为计费。 |
| `verify_type` | 认证类型，当前固定为 `real_time`。 |

### 火山方舟接口 Action

```text
ServiceName: ark
Version: 2024-01-01
Region: cn-beijing

CreateVisualValidateSession {
  "CallbackURL": "https://example.com/callback",
  "ProjectName": "default"
}

GetVisualValidateResult {
  "BytedToken": "20260331145619...",
  "ProjectName": "default"
}

CreateAssetGroup {
  "Name": "figure-group",
  "Description": "figure group",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

CreateAsset {
  "GroupId": "group-20260318070359-xxxxx",
  "URL": "https://example.com/person-front.jpg",
  "AssetType": "Image",
  "Name": "person-front",
  "ProjectName": "default"
}

GetAsset {
  "Id": "asset-20260318071009-xxxxx",
  "ProjectName": "default"
}

ListAssets {
  "Filter": {
    "GroupIds": ["group-20260318070359-xxxxx"],
    "GroupType": "AIGC",
    "Statuses": ["Active"]
  },
  "PageNumber": 1,
  "PageSize": 10,
  "ProjectName": "default"
}

ListAssetGroups {
  "Filter": {
    "Name": "figure",
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "ProjectName": "default"
}

GetAssetGroup {
  "Id": "group-20260318070359-xxxxx",
  "ProjectName": "default"
}

UpdateAsset {
  "Id": "asset-20260318071009-xxxxx",
  "Name": "new-asset-name",
  "ProjectName": "default"
}

UpdateAssetGroup {
  "Id": "group-20260318070359-xxxxx",
  "Name": "new-group-name",
  "Description": "new-description",
  "ProjectName": "default"
}

DeleteAsset {
  "Id": "asset-20260318071009-xxxxx",
  "ProjectName": "default"
}

DeleteAssetGroup {
  "Id": "group-20260318070359-xxxxx",
  "ProjectName": "default"
}
```

### Go 示例代码

示例代码通过火山 Go SDK 调用 `https://tp-api.chinadatapay.com:8000/seedance-gateway`，请先设置环境变量 `VOLC_ACCESS_KEY` 与 `VOLC_SECRET_KEY`。

公共前缀：

```go
package main

import (
  "fmt"
  "os"

  "github.com/bytedance/sonic"
  "github.com/volcengine/volcengine-go-sdk/volcengine"
  "github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
  "github.com/volcengine/volcengine-go-sdk/volcengine/session"
  "github.com/volcengine/volcengine-go-sdk/volcengine/universal"
)

func getEnv(key, fallback string) string {
  if v := os.Getenv(key); v != "" {
    return v
  }
  return fallback
}

func callArk(action string, body map[string]any) {
  ak := os.Getenv("VOLC_ACCESS_KEY")
  sk := os.Getenv("VOLC_SECRET_KEY")
  if ak == "" || sk == "" {
    fmt.Println("请先设置 VOLC_ACCESS_KEY 和 VOLC_SECRET_KEY")
    return
  }

  endpoint := getEnv("SEEDANCE_GATEWAY_BASE_URL", "https://tp-api.chinadatapay.com:8000/seedance-gateway")

  config := volcengine.NewConfig().
    WithCredentials(credentials.NewStaticCredentials(ak, sk, "")).
    WithRegion("cn-beijing")
  config.Endpoint = volcengine.String(endpoint)
  config.DisableRestProtocolURICleaning = volcengine.Bool(true)

  sess, err := session.NewSession(config)
  if err != nil {
    fmt.Printf("create session failed: %v\n", err)
    return
  }

  resp, err := universal.New(sess).DoCall(
    universal.RequestUniversal{
      ServiceName: "ark",
      Action:      action,
      Version:     "2024-01-01",
      HttpMethod:  universal.POST,
      ContentType: universal.ApplicationJSON,
    },
    &body,
  )
  if err != nil {
    fmt.Printf("sdk call failed: %+v\n", err)
    return
  }

  data, _ := sonic.Marshal(resp)
  fmt.Println(string(data))
}
```

#### CreateVisualValidateSession - 生成 H5 真人认证链接

```go
func main() {
  callArk("CreateVisualValidateSession", map[string]any{
    "CallbackURL": "https://example.com/callback",
    "ProjectName": "default",
  })
}
```

#### GetVisualValidateResult - 获取真人认证结果和 GroupId

```go
func main() {
  callArk("GetVisualValidateResult", map[string]any{
    "BytedToken": "20260331145619xxxxxxxx",
    "ProjectName": "default",
  })
}
```

#### CreateAssetGroup - 创建素材组

```go
func main() {
  callArk("CreateAssetGroup", map[string]any{
    "Name": "figure-group",
    "Description": "figure group",
    "GroupType": "AIGC",
    "ProjectName": "default",
  })
}
```

#### CreateAsset - 上传素材

```go
func main() {
  callArk("CreateAsset", map[string]any{
    "GroupId": "group-20260622183525-xxxxx",
    "URL": "https://example.com/person-front.jpg",
    "AssetType": "Image",
    "Name": "person-front",
    "ProjectName": "default",
  })
}
```

#### GetAsset - 查询单个素材

```go
func main() {
  callArk("GetAsset", map[string]any{
    "Id": "asset-20260622185318-xxxxx",
    "ProjectName": "default",
  })
}
```

#### ListAssets - 查询素材列表

```go
func main() {
  callArk("ListAssets", map[string]any{
    "Filter": map[string]any{
      "GroupIds": []string{"group-20260622183525-xxxxx"},
      "GroupType": "AIGC",
      "Statuses": []string{"Active", "Processing"},
      "Name": "person",
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc",
    "ProjectName": "default",
  })
}
```

#### ListAssetGroups - 查询素材组列表

```go
func main() {
  callArk("ListAssetGroups", map[string]any{
    "Filter": map[string]any{
      "Name": "figure",
      "GroupType": "AIGC",
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc",
    "ProjectName": "default",
  })
}
```

#### GetAssetGroup - 查询单个素材组

```go
func main() {
  callArk("GetAssetGroup", map[string]any{
    "Id": "group-20260622183525-xxxxx",
    "ProjectName": "default",
  })
}
```

#### UpdateAsset - 更新素材

```go
func main() {
  callArk("UpdateAsset", map[string]any{
    "Id": "asset-20260622185318-xxxxx",
    "Name": "new-asset-name",
    "ProjectName": "default",
  })
}
```

#### UpdateAssetGroup - 更新素材组

```go
func main() {
  callArk("UpdateAssetGroup", map[string]any{
    "Id": "group-20260622183525-xxxxx",
    "Name": "new-group-name",
    "Description": "new-description",
    "ProjectName": "default",
  })
}
```

#### DeleteAsset - 删除素材

```go
func main() {
  callArk("DeleteAsset", map[string]any{
    "Id": "asset-20260622185318-xxxxx",
    "ProjectName": "default",
  })
}
```

#### DeleteAssetGroup - 删除素材组

```go
func main() {
  callArk("DeleteAssetGroup", map[string]any{
    "Id": "group-20260622183525-xxxxx",
    "ProjectName": "default",
  })
}
```

### 用真人素材创建视频

```bash
curl https://tp-api.chinadatapay.com:8000/v1/video/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "图片1中的博主介绍图片2中的面霜，近景镜头，中文口播。"
      },
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-20260318071009-xxxxx" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/product.jpg" },
        "role": "reference_image"
      }
    ],
    "ratio": "16:9",
    "duration": 8,
    "resolution": "720p",
    "generate_audio": true
  }'
```

Prompt 中请使用“图片 1”“视频 1”等顺序描述参考素材，不要直接让模型理解 `asset_id`。

### 管理接口与限流

| 接口 | 用途 | 账号维度限流 |
|---|---|---|
| `CreateVisualValidateSession` | 创建 H5 真人认证会话 | 3 QPS |
| `GetVisualValidateResult` | 获取认证结果与 `GroupId` | 3 QPS |
| `CreateAsset` | 上传素材资产 | 按高级创作权益包配置 |
| `ListAssetGroups` / `GetAssetGroup` | 查询素材组 | 10 QPS |
| `ListAssets` | 按素材组、状态、名称筛选素材 | 10 QPS |
| `GetAsset` | 查询单个素材状态 | 100 QPS |
| `UpdateAsset` / `UpdateAssetGroup` | 更新素材或素材组信息 | 10 QPS |
| `DeleteAsset` | 删除单个素材 | 10 QPS |
| `DeleteAssetGroup` | 删除素材组 | 5 QPS |

Asset / Asset Group 管理接口只能查询、更新或删除当前账户内的素材组和素材。

---

## 5. 上传素材接口（支持AIGC真人）【旧】

`POST https://tp-api.chinadatapay.com:8000/v1/api/assets/upload`

用途：将外部 URL 指向的素材（图片 / 视频 / 音频）上传到上游素材库，落库后获得稳定的 asset_id，可在创建视频任务时通过 content[].image_url.url 等字段引用。

### 请求头

```http
Content-Type: application/json
Authorization: Bearer $ARK_API_KEY
```

### 必传 Query 参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | Seedance 模型名，例如 doubao-seedance-2.0 |

### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | 是 | 外部素材的 HTTP(S) URL（启用 SSRF 防护时必须为公网可达地址） |
| `asset_type` | string | 是 | Image / Video / Audio |
| `name` | string | 否 | 自定义名称，便于在列表接口中按名称筛选 |

### 请求示例

```bash
curl -X POST 'https://tp-api.chinadatapay.com:8000/v1/api/assets/upload?model=doubao-seedance-2.0' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "url": "https://example.com/lion.jpg",
    "asset_type": "Image",
    "name": "lion01"
  }'
```

### 响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | int/string | 0 或 "success" 表示成功，非 0 表示失败 |
| `message` | string | 错误描述 |
| `data.Id` | string | 上游分配的 asset_id，形如 asset-20260507175358-hmw2h |

### 响应示例

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "Id": "asset-20260507175358-hmw2h"
  }
}
```

### 错误说明

- 缺失 `?model` ：HTTP 400
- 缺失 `url` / `asset_type`：HTTP 400
- 上游 URL 命中 SSRF 黑名单（启用 SSRF 防护时）：HTTP 400
- 上游接口失败：原样回传上游 HTTP 状态码与错误体

---

## 6. 查询单个素材接口（支持AIGC真人）【旧】

`GET https://tp-api.chinadatapay.com:8000/v1/api/assets/{asset_id}`

用途：查询素材当前状态、签名 URL 等元信息。

### 请求头

```http
Authorization: Bearer $ARK_API_KEY
```

### 路径参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `asset_id` | string | 是 | 上传时返回的 data.Id，仅允许 [a-zA-Z0-9_\-]+ |

### 必传 Query 参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | Seedance 模型名，用于路由到对应渠道（与上传保持一致） |

### 所有权语义

调用方必须是该 asset_id 的上传者（即上传时使用的 token 所属 user）。

- 命中：返回结果
- 未命中：返回 HTTP 404

### 请求示例

```bash
curl 'https://tp-api.chinadatapay.com:8000/v1/api/assets/asset-20260507175358-hmw2h?model=doubao-seedance-2.0' \
  -H "Authorization: Bearer $ARK_API_KEY"
```

### 响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | int/string | 0 或 "success" 表示成功 |
| `message` | string | 错误描述 |
| `data.Id` | string | 素材 ID |
| `data.Name` | string | 自定义名称 |
| `data.AssetType` | string | Image / Video / Audio |
| `data.Status` | string | 上游状态：Active / Processing / Failed 等 |
| `data.URL` | string | 临时签名 URL（通常 12 小时过期，请按需重新查询） |
| `data.CreateTime` | string | 创建时间 |

### 响应示例

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "Id": "asset-20260507175358-hmw2h",
    "Name": "lion01",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://cdn.example.com/asset-...?Signature=...",
    "CreateTime": "2026-05-07T17:53:58Z"
  }
}
```

### 错误说明

- `asset_id` 不符合 `[a-zA-Z0-9_\-]+`：HTTP 400
- 当前 token 不是该 `asset_id` 的上传者：HTTP 404
- 缺失 `?model` ：HTTP 400

---

## 7. 使用素材创建视频

当成功将素材上传至素材库中后，可使用 `asset_id` 创建视频任务。

**注意：** `image_url` 中的 `url` 参数是可通过 `asset:// + asset_id` 拼接的（真人参考图请优先使用该方式，否则可能触发敏感风控），也可传入常规的 https 链接。

### 请求示例

```json
{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "一只猫在海边奔跑，电影感，夕阳，4k"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-20260507175358-hmw2h"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "duration": 4,
  "resolution": "720p",
  "execution_expires_after": 3600,
  "watermark": false
}
```

---

## 8. 计费规则

| 分辨率 | 含视频输入 | 不含视频输入 |
|---|---|---|
| 480P | 28元/百万tokens | 46元/百万tokens |
| 720P | 28元/百万tokens | 46元/百万tokens |
| 1080P | 31元/百万tokens | 51元/百万tokens |

实际价格以 [模型广场](/model) 为准。