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

# Seedance 2.0 素材管理

> 通过 Starrise AI API 管理 Seedance 2.0 视频生成所需的图片、视频和音频素材。

Seedance 2.0 素材管理让你可以上传和组织媒体素材（图片、视频、音频），供 Seedance 2.0 视频生成使用。上传后，在 Seedance 2.0 请求中通过素材 ID（`asset://<ID>`）引用素材，无需使用公开 URL。

## 为什么使用素材管理？

* **持久存储** — 素材存储在火山引擎，不会像临时 URL 那样过期
* **多格式支持** — 支持上传图片、视频和音频文件
* **分组管理** — 按项目或活动将相关素材归组
* **数据隔离** — 每个 API 令牌只能看到自己的素材
* **直接集成** — 在 Seedance 2.0 的 `image_url`、`video_url`、`audio_url` 字段中直接使用 `asset://<ID>`

## 支持的格式

| 类型     | 格式                                         | 限制                                  |
| ------ | ------------------------------------------ | ----------------------------------- |
| **图片** | JPG, PNG, GIF, WebP, BMP, TIFF, HEIC, HEIF | \< 30 MB，300–6000 px，宽高比 0.4–2.5    |
| **视频** | MP4, MOV                                   | \< 50 MB，2–15 秒，480p/720p，24–60 FPS |
| **音频** | MP3, WAV                                   | \< 15 MB，2–15 秒                     |

## 计费模型

| 模型名                | 素材类型 | 说明            |
| ------------------ | ---- | ------------- |
| `volc-asset`       | 图片   | 默认，上传图片无需指定   |
| `volc-asset-video` | 视频   | 上传视频时**必须**指定 |
| `volc-asset-audio` | 音频   | 上传音频时**必须**指定 |

## 工作流

```
1. 创建素材组              →  素材组 ID
2. 在素材组中创建素材       →  素材 ID
3. 使用素材生成视频         →  异步任务 ID
4. 轮询获取结果             →  预签名下载链接
```

## 第一步：创建素材组

首先创建一个素材组以获取素材组 ID。

<CodeGroup>
  ```bash cURL theme={null}
  curl https://ai.alad.com/volc/asset/CreateAssetGroup \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "volc-asset",
      "Name": "your-custom-name"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://ai.alad.com/volc/asset/CreateAssetGroup",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "volc-asset",
          "Name": "your-custom-name"
      }
  )

  group_id = response.json()["Id"]
  print(f"素材组 ID: {group_id}")
  ```
</CodeGroup>

预期响应：

```json theme={null}
{
  "Id": "group-20260427160000-xxxxx"
}
```

## 第二步：在素材组中创建素材

使用第一步获取的素材组 ID 上传素材（如角色参考图）。

<CodeGroup>
  ```bash cURL theme={null}
  curl https://ai.alad.com/volc/asset/CreateAsset \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "volc-asset",
      "GroupId": "group-20260427160000-xxxxx",
      "Name": "character-reference",
      "AssetType": "Image",
      "URL": "https://example.com/example.png"
    }'
  ```

  ```python Python theme={null}
  response = requests.post(
      "https://ai.alad.com/volc/asset/CreateAsset",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "volc-asset",
          "GroupId": "group-20260427160000-xxxxx",
          "Name": "character-reference",
          "AssetType": "Image",
          "URL": "https://example.com/example.png"
      }
  )

  asset_id = response.json()["Id"]
  print(f"素材 ID: {asset_id}")
  ```
</CodeGroup>

预期响应：

```json theme={null}
{
  "Id": "asset-20260427160000-xxxxx"
}
```

> `URL` 字段支持三种格式：
>
> * 普通 URL：`https://example.com/image.jpg`
> * Data URI：`data:image/png;base64,iVBOR...`
> * 纯 Base64 字符串（自动识别，默认当作 PNG）
>
> Base64 / Data URI 会自动上传到对象存储并替换为真实 URL。

### 上传视频

> 上传视频时**必须**指定 `"model": "volc-asset-video"` 和 `"AssetType": "Video"`。

```bash cURL theme={null}
curl https://ai.alad.com/volc/asset/CreateAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volc-asset-video",
    "GroupId": "group-20260427160000-xxxxx",
    "Name": "reference-clip",
    "AssetType": "Video",
    "URL": "https://example.com/clip.mp4"
  }'
```

### 上传音频

> 上传音频时**必须**指定 `"model": "volc-asset-audio"` 和 `"AssetType": "Audio"`。

```bash cURL theme={null}
curl https://ai.alad.com/volc/asset/CreateAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volc-asset-audio",
    "GroupId": "group-20260427160000-xxxxx",
    "Name": "background-music",
    "AssetType": "Audio",
    "URL": "https://example.com/bgm.mp3"
  }'
```

### 文件上传（multipart）

```bash 上传图片 theme={null}
curl https://ai.alad.com/volc/asset/CreateAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg" \
  -F "GroupId=group-20260427160000-xxxxx" \
  -F "Name=character-reference"
```

```bash 上传视频 theme={null}
curl https://ai.alad.com/volc/asset/CreateAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=volc-asset-video" \
  -F "file=@/path/to/video.mp4" \
  -F "GroupId=group-20260427160000-xxxxx" \
  -F "Name=reference-clip" \
  -F "AssetType=Video"
```

```bash 上传音频 theme={null}
curl https://ai.alad.com/volc/asset/CreateAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=volc-asset-audio" \
  -F "file=@/path/to/audio.mp3" \
  -F "GroupId=group-20260427160000-xxxxx" \
  -F "Name=background-music" \
  -F "AssetType=Audio"
```

## 第三步：使用素材生成视频

引用第二步获取的素材 ID 生成视频。

> **重要：** 素材需严格按照 text、image\_url、video\_url、audio\_url 的顺序传入。请勿调整顺序，否则可能导致报错；当包含多个素材时，也需确保其中不混入其他类型的素材。

```bash cURL theme={null}
curl https://ai.alad.com/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance",
    "content": [
      {
        "type": "text",
        "text": "@图1 中的人物走在 @视频1 的场景中，背景音乐使用 @音频1"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-20260427160000-xxxxx"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "asset://asset-20260427160000-video1"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "asset://asset-20260427160000-audio1"
        },
        "role": "reference_audio"
      }
    ],
    "resolution": "720p",
    "duration": 5
  }'
```

响应将返回一个异步任务 ID（以 `asyn` 为前缀）。

## 第四步：轮询获取结果

使用任务 ID 检查生成状态。

```bash cURL theme={null}
curl https://ai.alad.com/v1/video/generations/asynxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"
```

完成后，响应将包含一个预签名的 S3 下载链接。请注意：

* 下载链接**12 小时后过期**。
* 如果任务进度达到 100% 但返回错误，通常表示输出被服务方内容审核拦截（例如名人肖像或受版权保护的 IP）。这种情况下请尝试修改提示词或更换参考图。

## 查询素材

### 查询素材组

```bash cURL theme={null}
curl https://ai.alad.com/volc/asset/ListAssetGroups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volc-asset",
    "Filter": {"Name": "my-project"},
    "PageNumber": 1,
    "PageSize": 10
  }'
```

### 查询素材组内的素材

```bash cURL theme={null}
curl https://ai.alad.com/volc/asset/ListAssets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volc-asset",
    "Filter": {
      "Name": "character",
      "GroupIds": ["group-20260427160000-xxxxx"],
      "GroupType": "AIGC"
    },
    "PageNumber": 1,
    "PageSize": 10
  }'
```

## 计费说明

| 操作               | 计费模型               | 是否计费 |
| ---------------- | ------------------ | ---- |
| CreateAssetGroup | `volc-asset`       | 不计费  |
| CreateAsset（图片）  | `volc-asset`       | 不计费  |
| CreateAsset（视频）  | `volc-asset-video` | 不计费  |
| CreateAsset（音频）  | `volc-asset-audio` | 不计费  |
| ListAssetGroups  | —                  | 不计费  |
| ListAssets       | —                  | 不计费  |

## 数据隔离

使用令牌访问时，系统自动为素材组名称添加 `[u-{用户ID}]-[t-{令牌ID}]` 前缀，实现用户和令牌级别的数据隔离。查询时自动过滤，仅返回当前令牌有权限的数据。

## API 参考

<CardGroup cols={2}>
  <Card title="创建素材组" icon="folder-plus" href="/zh/api-reference/model-api/bytedance/volc-asset-create-group">
    创建新的素材组。
  </Card>

  <Card title="创建素材" icon="upload" href="/zh/api-reference/model-api/bytedance/volc-asset-create-group">
    上传素材（图片、视频、音频）到素材组。
  </Card>

  <Card title="查询素材组" icon="folders" href="/zh/api-reference/model-api/bytedance/volc-asset-list-groups">
    查询素材组列表。
  </Card>

  <Card title="查询素材" icon="images" href="/zh/api-reference/model-api/bytedance/volc-asset-list-assets">
    查询素材组内的素材。
  </Card>
</CardGroup>