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

# Seedance 2.0 素材管理

> 通过 Anyfast 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. 轮询获取结果             →  预签名下载链接
```

## 真人活体认证工作流

当你需要创建私域真人肖像素材组时，使用 LivenessFace 流程。Anyfast 会创建一个移动端认证页面，用户在手机上完成真人活体认证后，认证结果会生成一个 `LivenessFace` 素材组。

<Tip>
  完整授权流程和官方术语请参见[录入真人形象素材](/guides/model-api/bytedance/volc-real-human-assets)指南。
</Tip>

<Warning>
  真人活体认证必须使用选择了 **Direct** 分组的 API 令牌。普通 AIGC 素材分组仅支持 `GroupType: "AIGC"`，无法创建真人认证会话或 LivenessFace 真人素材。
</Warning>

<Steps>
  <Step title="创建认证会话">
    调用 `CreateVisualValidateSession` 获取 `H5Link` 和 `BytedToken`。

    ```bash cURL theme={null}
    curl https://www.anyfast.com.cn/volc/asset/CreateVisualValidateSession \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "CallbackURL": "https://example.com/callback"
      }'
    ```
  </Step>

  <Step title="在手机上打开 H5Link">
    将返回的 `H5Link` 发给用户，用户在手机上完成真人活体认证。
  </Step>

  <Step title="查询认证结果">
    认证完成后，使用 `BytedToken` 调用 `GetVisualValidateResult`。认证成功会返回 `GroupId`。

    ```bash cURL theme={null}
    curl https://www.anyfast.com.cn/volc/asset/GetVisualValidateResult \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "BytedToken": "2026070222152680501D985EA34A3BE3D8"
      }'
    ```
  </Step>

  <Step title="管理 LivenessFace 素材组">
    将返回的 `GroupId` 用于 `ListAssetGroups`、`CreateAsset`、`ListAssets` 和 `GetAsset`。查询真人认证素材组或素材时，请传入 `Filter.GroupType: "LivenessFace"`。
  </Step>
</Steps>

<Note>
  如果认证未完成或未生成素材组，`GetVisualValidateResult` 可能返回 `{"GroupId": ""}`。无效或过期的 token 会返回上游错误。
</Note>

<Note>
  向 LivenessFace 素材组上传图片时，图片人脸需要与真人认证的人一致。不一致时会返回 `FaceMismatch`，素材状态为 `Failed`。
</Note>

## 第一步：创建素材组

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/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://www.anyfast.com.cn/v1/video/generations/asynxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

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

## 查询素材

### 查询素材组

```bash cURL theme={null}
curl https://www.anyfast.com.cn/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://www.anyfast.com.cn/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` | 不计费  |
| CreateVisualValidateSession | —                  | 不计费  |
| GetVisualValidateResult     | —                  | 不计费  |
| ListAssetGroups             | —                  | 不计费  |
| ListAssets                  | —                  | 不计费  |

## 数据隔离

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

## API 参考

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

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

  <Card title="创建真人认证会话" icon="scan-face" href="/api-reference/model-api/bytedance/volc-asset-create-visual-validate-session">
    创建移动端真人活体认证会话。
  </Card>

  <Card title="查询真人认证结果" icon="badge-check" href="/api-reference/model-api/bytedance/volc-asset-get-visual-validate-result">
    查询认证会话创建的 LivenessFace 素材组。
  </Card>

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

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

<script src="/feedback.js" />