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

# 虚拟人像素材

> 通过本网关提交和引用 Seedance 2.0 虚拟人像素材。

使用本网关创建的 API 密钥调用以下接口。当前仅 `seedance-2.0` 支持 `private_avatar` 素材；素材源必须是上游可访问的公开 HTTPS 地址，本接口不接收本地文件。素材需通过审核后才能引用。

## 提交素材

`POST /v1/media-assets` 提交审核任务。下面的 `asset_group` 用于新建素材组；加入已有素材组时，改传 `group_id`，两者必须且只能提供一个。`assets` 一次可传 1–20 项。

```bash theme={null}
curl -X POST "$BASE_URL/v1/media-assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "kind": "private_avatar",
    "asset_group": {"name": "actors"},
    "project_name": "default",
    "asset_type": "Image",
    "assets": [{"url": "https://example.com/actor.png", "name": "actor"}]
  }'
```

`project_name` 省略时为 `default`，`asset_type` 省略时为 `Image`；也可填 `Video` 或 `Audio`。如果需要指定本网关的渠道分组，使用顶层 `group`，不要将它与上游素材组的 `asset_group` 混淆。所选渠道须支持该模型，并且只能配置一把上游密钥。

响应为 HTTP 202，例如：

```json theme={null}
{"id":"mas_...","object":"media_asset_submission","status":"processing"}
```

这里的 `id` 是素材审核提交 ID，不是视频生成任务 ID。

## 查询审核与素材

用同一账号的 API 密钥调用 `GET /v1/media-assets/submissions/{id}` 查询审核状态：

```bash theme={null}
curl "$BASE_URL/v1/media-assets/submissions/mas_..." \
  -H "Authorization: Bearer $API_KEY"
```

完成后，通过审核的素材会返回上游原始地址：

```json theme={null}
{
  "id": "mas_...",
  "object": "media_asset_submission",
  "model": "seedance-2.0",
  "kind": "private_avatar",
  "status": "completed",
  "assets": [{
    "id": "ma_...",
    "submission_id": "mas_...",
    "url": "asset://asset_a",
    "asset_url": "asset://asset_a",
    "status": "Active"
  }]
}
```

只有状态为 `Active` 的素材会带有可引用地址。部分审核未通过时，仍可能有通过的素材。`GET /v1/media-assets` 可列出当前账号的素材：

```bash theme={null}
curl "$BASE_URL/v1/media-assets" -H "Authorization: Bearer $API_KEY"
```

## 生成视频

将通过审核的 `asset_url` 原样放入 `image_urls`，使用统一的视频接口 **`POST /v1/videos`**：

```bash theme={null}
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "人物面对镜头自然说话",
    "duration": 5,
    "image_urls": ["asset://asset_a"]
  }'
```

也可以把素材地址放入 `image_with_roles[].url`，但不能与 `image_urls` 同时使用。返回视频任务 ID 后，按 [任务查询](/videos/task) 获取生成结果。素材必须属于当前账号和同一上游渠道；来自不同渠道的素材不能在同一请求中混用。未登记或已从本网关移除的 `asset://` 地址无法引用。

## 移除素材

使用素材列表中的 `id`（`ma_...`）执行 `DELETE /v1/media-assets/{id}`：

```bash theme={null}
curl -X DELETE "$BASE_URL/v1/media-assets/ma_..." \
  -H "Authorization: Bearer $API_KEY"
```

成功时返回 HTTP 204。此操作仅移除本网关中的素材引用，不会删除上游已创建的素材。之前返回的 `media://ma_...` 引用仍可用于已有素材。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.