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

# 创建任务（火山兼容）

> 使用火山风格 REST body 或 Action 请求创建 Seedance 2.0 任务。

## 概览

这些接口面向已经使用火山风格 Seedance 任务结构的团队。它们保留任务式请求和响应结构，同时使用 AI Sonar 的鉴权、计费、模型可用性和任务轮询。

另见 [Seedance 2.0 视频模型](/zh/guides/seedance-2-video) 和 [视频生成](/zh/guides/video-generation)。

## 鉴权与入口

* 使用 `Authorization: Bearer <API_KEY>`。
* 当前版本不接受火山 AK/SK 签名。只带 AK/SK 签名而没有 AI Sonar Bearer 的请求会返回火山风格鉴权错误。
* `Version` 可省略；如传入，必须为 `2024-01-01`。

| 方式        | 请求                                                                      |
| --------- | ----------------------------------------------------------------------- |
| REST 创建   | `POST /api/v3/contents/generations/tasks`                               |
| Action 创建 | `POST /api/v3?Action=CreateContentsGenerationsTasks&Version=2024-01-01` |

## 内容规则

* `type: "text"` 表示提示词文本。
* `type: "image_url"` 不传 `role` 或传 `role: "first_frame"` 时按首帧处理。
* `role: "last_frame"` 必须和首帧一起使用。
* `role: "reference_image"`、`reference_video`、`reference_audio` 表示参考素材。
* `image_url.url` 可以是公网图片 URL，也可以是 `asset://asset-YYYYMMDDHHMMSS-xxxxx` 形式的 AI Sonar 素材 URI；`role` 决定该素材是首帧、尾帧还是参考图。
* AI Sonar 额外兼容一个顶层 `material_asset_id`，并将其按首帧处理。多个顶层 `material_asset_ids` 因用途不明确会被拒绝；请改放到 `content[]` 中并为每个素材明确填写 `role`。
* 同一个请求里不要混用首尾帧输入和参考素材。

## 参数说明

* `ratio` 支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9` 或 `adaptive`。
* `duration` 表示秒数，也支持模型允许的自动时长值。
* `resolution` 可传 `480p`、`720p`、`1080p` 或 `4k`，以前提是所选 Seedance 模型支持。
* `generate_audio` 默认是 `true`；需要静音视频时传 `false`。
* `watermark`、`return_last_frame`、`seed`、`priority`、`execution_expires_after` 和 `safety_identifier` 在符合所选模型规则时可用。
* `callback_url` 暂不支持；请轮询任务状态。

## 图片准备

`content[]` 中包含图片 URL 时，AI Sonar 会在所选 Seedance 模型需要素材引用时把它们准备为可复用素材。如果 60 秒内仍未准备完成，创建请求会返回可重试的素材准备中错误，而不是提交一个不完整的视频任务。

使用已有 AI Sonar 素材时，请传公开的 `asset-YYYYMMDDHHMMSS-xxxxx` ID，不要传其他系统返回的原始素材 ID。AI Sonar 会在生成前校验素材归属。

## 创建响应

```json theme={null}
{
  "id": "cgt-0123456789abcdef0123456789abcdef"
}
```

创建响应只包含兼容任务 ID。保存这个 ID，并调用查询任务接口轮询结果。

## 示例

### REST 创建

```bash theme={null}
curl https://api.aisonar.dev/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": true
  }'
```

如果只使用一个已有素材作为首帧，可以让 `content[]` 只包含文本，并额外传入：

```json theme={null}
{
  "material_asset_id": "asset-20260720123456-qn7wr"
}
```

如果有多个素材，请把每个素材放进 `content[]` 并明确用途：

```json theme={null}
[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]
```

### Action 创建

```bash theme={null}
curl "https://api.aisonar.dev/api/v3?Action=CreateContentsGenerationsTasks&Version=2024-01-01" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "A clean product reveal video"}],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'
```

## 下一步

使用返回的 `cgt-...` ID 调用 [查询任务（火山兼容）](/zh/api-reference/video/get-volc-compatible-seedance-task)，直到任务进入终态。