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

# Seedance 2.0 视频模型

> 使用 Seedance 2.0 视频生成功能，支持虚拟人像和真人素材组。

Seedance 2.0 支持文生视频、图生视频、首尾帧视频、参考图生视频、视频编辑和视频扩展。请使用 `seedance-2.0`、`seedance-2.0-fast` 和 `seedance-2.0-mini` 等模型 ID，并通过 `operation` 选择工作流。

## 模型选择

| 模型                  | 适用场景        | 支持的分辨率                        |
| ------------------- | ----------- | ----------------------------- |
| `seedance-2.0`      | 最高质量和 4K 输出 | `480p`, `720p`, `1080p`, `4k` |
| `seedance-2.0-fast` | 更快、成本更低的输出  | `480p`, `720p`                |
| `seedance-2.0-mini` | 最低成本输出      | `480p`, `720p`                |

`seedance-2.0-fast` 和 `seedance-2.0-mini` 不支持 `1080p` 和 `4k` 请求。音频仅可在支持的参考工作流中使用；不支持纯音频或仅文本加音频的 Seedance 请求。

## 支持的操作

| 操作                   | 典型输入                                                           |
| -------------------- | -------------------------------------------------------------- |
| `text-to-video`      | `prompt`                                                       |
| `image-to-video`     | `prompt`, `image_url` 或兼容的图像输入                                 |
| `start-end-to-video` | `prompt`, `start_image`, `end_image`                           |
| `reference-to-video` | `prompt`, `reference_images`, 可选 `video_urls`, 可选 `audio_urls` |
| `video-to-video`     | `prompt`, `video_url` 或兼容的视频输入                                 |
| `video-extension`    | `task_id` 或模型特定的续写输入                                           |

## 素材概念

Seedance 素材是可复用的、组织范围内的引用，可在后续视频生成过程中进行选择。

| 概念      | 公共字段                            | 含义                                                          |
| ------- | ------------------------------- | ----------------------------------------------------------- |
| 素材组     | `group_id`                      | 拥有相关 Seedance 素材的 AI Sonar 组。在上传或列出素材时使用。                   |
| 素材资产    | `id`                            | 单个上传的图像、视频或音频文件。资产变为 `ACTIVE` 后，请将此值用作 `material_asset_id`。 |
| 虚拟人像素材组 | `library_type: "aigc_avatar"`   | 用于虚拟人像、产品、风格及其他无需真人验证的可复用引用。                                |
| 真人素材组   | `library_type: "liveness_face"` | 通过真人素材验证创建。一个组代表一个已验证的真人。                                   |

请区分 `group_id` 和素材资产 `id`。`group_id` 用于组织上传；素材资产 `id` 用于视频生成。如果视频请求返回 `Seedance material asset not found or not accessible`，请确认您传入的是素材资产 `id` 而非 `group_id`，并确保该资产属于同一组织、未被删除且状态为 `status: "ACTIVE"`。

## 自动图片素材

当所选 Seedance 模型可使用 AI Sonar 素材库时，您可以直接在 `image`、`image_url`、`image_urls`、`reference_images`、`start_image` 或 `end_image` 中传入图片 URL 或受支持的内联 data URL。AI Sonar 会把这些图片导入组织默认的虚拟人像素材组，并保留其首帧、尾帧或参考图角色。

如果素材在 60 秒内变为 `ACTIVE`，同一个请求会继续进入生成。如果尚未准备完成，API 会返回 `409 seedance_material_preparing` 和 `auto_material_asset_ids`；请查询这些素材直到它们变为 `ACTIVE`，再使用 `material_asset_id` 或 `material_asset_ids` 重试。如果所选模型暂不可使用素材库，普通图片 URL 或 data URL 会继续走常规图片路径；显式素材 ID 会返回素材可用性错误。已有虚拟人像素材 ID 和真人素材 ID 会原样使用，不会重复导入。

## 真人素材验证

当您的产品在使用真人作为可复用的 Seedance 引用前需要获得同意并进行人脸验证时，请使用真人素材验证。

1. 调用 [创建视觉验证会话](/zh/api-reference/video/create-visual-validation-session)，传入 `CallbackURL`，并保存返回的 `Result.BytedToken`。
2. 为待验证人员打开 `Result.H5Link`。如需指定语言，请在 H5 链接后追加 `lng`。
3. H5 流程完成后，浏览器会打开 `Result.CallbackURL`，并携带 `bytedToken`、`resultCode` 等官方查询参数。
4. 使用 `BytedToken` 轮询 [获取视觉验证结果](/zh/api-reference/video/get-visual-validation-result)，直到返回 `Result.GroupId`。
5. 保存 `GroupId`；创建 `liveness_face` 素材时将其作为 `group_id`。

`BytedToken` 的有效期为 30 分钟。两次 Action 请求必须使用相同的 `ProjectName`。认证使用 `Authorization: Bearer <API_KEY>`，不接受火山引擎 AK/SK 签名。

可选：使用 [测试控制台](https://console.aisonar.dev/customer/seedance-assets) 来验证您的请求和回调流程、检查素材组并查看验证历史。您的生产环境集成应直接调用 API。

## 创建素材组

使用 [创建素材资产组](/zh/api-reference/video/create-material-asset-group) 创建 `aigc_avatar` 组。新的真人组通过验证流程创建，以便将已验证的个人与素材组关联。

使用 [列出素材资产组](/zh/api-reference/video/list-material-asset-groups)、[获取素材资源组](/zh/api-reference/video/get-material-asset-group)、[更新素材资产组](/zh/api-reference/video/update-material-asset-group) 和 [删除素材资源组](/zh/api-reference/video/delete-material-asset-group) 在组创建后进行管理。

删除素材组也会删除其中包含的 AI Sonar 素材，且该操作不可撤销。如果 AI Sonar 素材库因当前授权状态不允许而无法完成删除，AI Sonar 将返回一个中性的素材库错误。

## 上传素材

使用 [创建素材资产](/zh/api-reference/video/create-material-asset) 每次导入一个可公开访问的源 URL。

对于 `aigc_avatar`，`group_id` 是可选的；AI Sonar 将使用或创建组织默认的虚拟人像组。对于 `liveness_face`，`group_id` 是必需的，且必须是 [获取视觉验证结果](/zh/api-reference/video/get-visual-validation-result) 返回的组 ID。

| 类型 | 支持的输入                                                                                                                            |
| -- | -------------------------------------------------------------------------------------------------------------------------------- |
| 图像 | `jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`, `heic`, `heif`；宽高比 `(0.4, 2.5)`；宽和高 `(300, 6000)` px；小于 30 MB。                      |
| 视频 | `mp4`, `mov`；`480p`, `720p` 或 `1080p`；2-15 秒；宽高比 `[0.4, 2.5]`；宽和高 `[300, 6000]` px；总像素在 409600 到 2068676 之间；最大 200 MB；24-60 FPS。 |
| 音频 | `aac`, `wav`, `mp3`；2-15 秒；最大 15 MB。                                                                                             |

AI Sonar 会校验源 URL、声明或探测到的媒体格式以及文件大小上限。宽高、宽高比、时长、分辨率、总像素和 FPS 采用 best effort 透传，最终由所选视频服务判断素材是否合格。

素材摄取是异步的。请轮询 [获取素材资源](/zh/api-reference/video/get-material-asset) 直到 `status` 变为 `ACTIVE`。成功的 HTTP 响应仅表示请求已被接受；请务必读取业务状态。如果状态为 `FAILED`，请检查 `error_message`，修复源素材并创建新资产。

在创建素材请求中，`asset_url` 只表示导入来源。AI Sonar 会返回素材资产 `id`；生成视频时请使用这个 `id`，不要继续使用原始 URL。

素材与素材组 ID 使用火山兼容外观，例如 `asset-20260720123456-qn7wr` 和 `group-20260720123456-vrt01`，但它们仍是 AI Sonar 自有映射 ID。

AI Sonar 会将素材保留在您的组织素材库中，直到您删除该素材或其所在素材组。

对于真人素材组，一个组对应一个真人。上传内容会与已验证的人脸进行比对。包含多个人脸或人脸与已验证个人不匹配的资产可能会失败。为获得最佳效果，请同时上传一张全身正面参考图和一张人脸清晰的正面特写图。

## 在视频生成中使用素材

资产变为 `ACTIVE` 后，在调用 [创建视频](/zh/api-reference/video/create-video) 时，将返回的 AI Sonar 资产 `id` 作为 `material_asset_id` 传入，或将其包含在 `material_asset_ids` 中。素材资产计入 Seedance 参考限制。

## API 示例

创建一个虚拟人像组，上传一张图像，轮询直到其处于激活状态，然后在视频请求中使用该素材资产 ID。

```bash theme={null}
curl https://api.aisonar.dev/v1/videos/assets/groups \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.aisonar.dev/v1/videos/assets \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.aisonar.dev/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $API_KEY"
```

对于真人素材组，请先创建视觉验证会话并获取验证结果，再上传素材。

```bash theme={null}
curl 'https://api.aisonar.dev/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.aisonar.dev/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'
```

## 定价与异步结果

Seedance 2.0 的定价取决于输出分辨率、输入类型和模型。在硬编码产品 UI 之前，请使用 [Pricing API](/zh/api-reference/pricing/get-pricing) 或 [Models API](/zh/api-reference/models/list-models)。

视频生成是异步的。请遵循创建请求返回的 `poll_url`，或使用返回的任务 ID 调用 [获取任务状态](/zh/api-reference/tasks/get-task-status)。

## 火山风格 Seedance 兼容入口

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

### 接入流程

1. 使用 `Authorization: Bearer <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 模型里会自动准备为 AI Sonar 可复用素材。若 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)