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

# 从火山迁移 Seedance

> 以最小请求改动把火山风格的 Seedance 任务和素材接入迁移到 TokenLab。

如果你的应用已经发送火山风格的 Seedance 请求，请使用本指南。Action 名称、`Version=2024-01-01`、`content[]`、PascalCase 素材请求体和火山响应信封都可以保留；必须修改的是接口地址和鉴权方式。

## 需要修改的内容

| 项目        | 现有火山客户端             | TokenLab                                   |
| --------- | ------------------- | ------------------------------------------ |
| 基础 URL    | `Volcengine API`    | `https://api.tokenlab.sh/`                 |
| 鉴权        | `AK/SK`             | `Authorization: Bearer <TOKENLAB_API_KEY>` |
| Action 请求 | `Action`, `Version` | `Action`, `Version`                        |
| 任务请求体     | `content[]`         | `content[]`                                |
| 素材请求体     | `PascalCase`        | `PascalCase`                               |
| 异步结果      | `任务 ID`             | `cgt-...` + 轮询                             |

仅带 AK/SK 的请求会返回 `401 InvalidCredential`。Action 客户端可使用 `POST /?Action=...&Version=2024-01-01`；`POST /api/v3?Action=...&Version=2024-01-01` 仍然可用。REST 任务客户端使用 `/api/v3/contents/generations/tasks`。

## 请求形状与任务生命周期

如果你的系统已经按火山风格组织 Seedance 请求，例如使用 `content[]`、REST 任务路径或 Action 名称，可以使用兼容入口，只替换域名和鉴权方式，不必先把请求体改成 `/v1/videos/generations` 的统一格式。新的跨模型视频接入仍建议优先使用 TokenLab 统一的 [`/v1/videos/generations`](/zh/api-reference/video/create-video)。

### 接入流程

1. 使用 `Authorization: Bearer <TOKENLAB_API_KEY>` 鉴权。当前版本不接受火山 AK/SK 签名。
2. REST 创建使用 `POST /api/v3/contents/generations/tasks`；Action 创建使用 `POST /api/v3?Action=CreateContentsGenerationsTasks&Version=2024-01-01`。
3. 创建响应返回 `cgt-...` 任务 ID。用查询任务接口轮询，直到 `status` 变为 `succeeded`、`failed`、`cancelled` 或 `expired`。
4. `callback_url` 当前会被明确拒绝，请不要把它当作可用回调；本入口使用轮询拿结果。

### 请求体要点

* `content[]` 支持 `text`、`image_url`、`video_url`、`audio_url` 和 `draft_task`。
* `image_url` 不传 `role` 或传 `first_frame` 时表示首帧；`last_frame` 必须和首帧一起使用；`reference_image` 表示参考图。
* 图片 URL 在需要素材引用的 Seedance 模型里会自动准备为 TokenLab 可复用素材。若 60 秒内仍未准备完成，创建请求会返回可重试的素材准备中错误。
* 常用生成字段包括 `model`、`ratio`、`duration`、`resolution`、`generate_audio`、`watermark`、`return_last_frame`、`seed`、`priority`、`execution_expires_after` 和 `safety_identifier`。

### 参考页面

* [创建任务（火山兼容）](/zh/api-reference/video/create-volc-compatible-seedance-task)
* [查询任务（火山兼容）](/zh/api-reference/video/get-volc-compatible-seedance-task)
* [任务列表（火山兼容）](/zh/api-reference/video/list-volc-compatible-seedance-tasks)
* [取消任务（火山兼容）](/zh/api-reference/video/delete-volc-compatible-seedance-task)

## 任务 Action

| Action                           | 项目      | JSON                 |
| -------------------------------- | ------- | -------------------- |
| `CreateContentsGenerationsTasks` | 创建视频任务  | `model`, `content[]` |
| `GetContentsGenerationsTask`     | 获取单个任务  | `TaskId`             |
| `ListContentsGenerationsTasks`   | 列出任务    | 筛选、分页                |
| `DeleteContentsGenerationsTasks` | 取消或删除任务 | `TaskId`             |

## 最小 Action 示例

```bash theme={null}
curl 'https://api.tokenlab.sh/?Action=CreateContentsGenerationsTasks&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.0",
    "content":[
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio":"16:9",
    "duration":5,
    "resolution":"720p"
  }'
```

## 素材与真人验证

同一个 Action 入口也支持 10 个素材和素材组操作。请查看[火山兼容素材 Action](/zh/api-reference/video/volc-compatible-material-actions)了解 PascalCase 请求体、筛选、分页、响应信封和 12 小时素材 URL。真人素材在上传前还需要调用[创建视觉验证会话](/zh/api-reference/video/create-visual-validation-session)和[获取视觉验证结果](/zh/api-reference/video/get-visual-validation-result)。

## 迁移检查清单

1. 把 API 主机替换为 `https://api.tokenlab.sh`。
2. 把 AK/SK 签名替换为 TokenLab Bearer API Key。
3. 保留现有 Action、版本和请求体大小写。
4. 相关素材和真人验证请求使用相同的 `ProjectName`。
5. 保存 TokenLab 返回的任务、素材组和素材 ID。
6. 迁移生产流量前验证创建、轮询、列表和错误响应。