Seedance 私域素材库 - 数字先锋API文档

# Seedance 私域素材库 API 对接文档

> **用途**：第三方软件 / 自有二开工具对接「虚拟人物形象入库」能力
> **解决的问题**：Seedance 视频生成内置 Deepfake/肖像权检测，直接传参考图 URL 可能被「疑似真人」误判拦截（400 PrivacyInformation）。素材入库（Active）后使用 `asset://<id>` 引用即可绕过拦截，走可信链路。
> **适用对象**：云灵API 平台会员（需已开通素材管理功能）

---

## 1. 快速开始（三步）

```bash
# ① 查询配额与默认素材组（拿到 group_id）
curl https://api.cxsee.com/v1/assets/quota \
  -H "Authorization: Bearer <你的API令牌>"

# ② 上传一张 AI 生成的虚拟人物图片（公开 URL）
curl -X POST https://api.cxsee.com/v1/assets \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-20260812091334-msdtl",
    "url": "https://example.com/virtual-figure.png",
    "asset_type": "Image",
    "name": "角色A-正面"
  }'

# ③ 轮询素材状态至 Active，然后用 asset://<asset_id> 生成视频
```

---

## 2. 鉴权方式

所有接口使用 **API 令牌**（Bearer Token）鉴权：

| 项 | 值 |
|---|---|
| Header | `Authorization: Bearer <API 令牌>` |
| 令牌获取 | 登录平台控制台 →「令牌」页面创建；或注册/OAuth/微信登录后自动生成的默认密钥 |
| 内容类型 | `Content-Type: application/json`（上传/创建类接口） |

**两套通道**（二开时按场景选择）：

| 通道 | 路径前缀 | 鉴权 | 适用场景 |
|---|---|---|---|
| API 通道 | `/v1/assets/*` | Bearer API 令牌 | 第三方软件、服务端、脚本 |
| Web 通道 | `/api/assets/*` | 网页登录态（Session） | 网页端二开、控制台功能 |

> 本文档以 API 通道为例，Web 通道路径、参数、返回完全一致。

---

## 3. 接口总览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/v1/assets/quota` | 配额查询（used / quota / remain / group_id） |
| GET | `/v1/assets/groups` | 素材组列表 |
| POST | `/v1/assets/groups` | 创建素材组 |
| POST | `/v1/assets` | 上传素材（图片 URL） |
| GET | `/v1/assets` | 素材列表（仅自己的素材） |
| GET | `/v1/assets/:asset_id` | 素材详情 |
| DELETE | `/v1/assets/:asset_id` | 删除素材（释放配额） |

Base URL：`https://api.cxsee.com`

---

## 4. 接口详情

### 4.1 配额查询

```http
GET /v1/assets/quota
```

**返回**：

```json
{
  "success": true,
  "data": {
    "used": 1,
    "quota": 50,
    "remain": 49,
    "group_id": "group-20260812091334-msdtl"
  }
}
```

- `quota`：配额上限（默认 50，存量限制）
- `group_id`：平台默认素材组，**新用户直接用它上传即可**

---

### 4.2 素材组列表

```http
GET /v1/assets/groups
```

**可选参数**：`name`（组名模糊）、`group_id`（精确）

**返回**（火山原生结构）：

```json
{
  "Result": {
    "TotalCount": 1,
    "Items": [
      {
        "Id": "group-20260812091334-msdtl",
        "Name": "default",
        "Description": "",
        "GroupType": "AIGC",
        "CreateTime": "2026-08-12T01:13:34Z"
      }
    ]
  }
}
```

---

### 4.3 创建素材组（可选）

一般**无需创建**，直接用默认组即可；需要分类管理时可创建。

```http
POST /v1/assets/groups
Content-Type: application/json

{
  "name": "my_figure_group",
  "description": "我的虚拟角色库"
}
```

---

### 4.4 上传素材（核心）

```http
POST /v1/assets
Content-Type: application/json
```

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `group_id` | string | ✅ | 素材组 ID（默认组见配额接口返回） |
| `url` | string | ✅ | **公开可访问**的图片 URL（PNG/JPG 等） |
| `asset_type` | string | ❌ | `Image`（默认） |
| `name` | string | ❌ | 素材名称（建议填，便于管理） |

**返回**：

```json
{
  "Result": {
    "Id": "asset-20260812100000-ab12cd",
    "Status": "Processing",
    "CreateTime": "2026-08-12T02:00:00Z",
    "URL": "https://example.com/virtual-figure.png",
    "Name": "角色A-正面"
  }
}
```

**图片格式要求**：

- 格式：jpeg / png / webp / bmp / tiff / gif / heic / heif
- 尺寸：宽高比 (0.4, 2.5)，边长 (300, 6000)px，<30MB
- 人像最佳实践：全身正面竖版，或肩部以上无表情特写（面部占 2/3）
- ⚠️ **多张人脸无法入库**；禁止与真实自然人肖像雷同

---

### 4.5 素材列表

```http
GET /v1/assets
```

**可选参数**：`group_id`、`status`（逗号分隔，如 `Active,Processing`）

**返回**（仅当前用户的素材）：

```json
{
  "Result": {
    "TotalCount": 1,
    "Items": [
      {
        "Id": "asset-20260812091800-287bf",
        "Name": "img1",
        "Status": "Active",
        "URL": "https://...",
        "GroupId": "group-20260812091334-msdtl",
        "CreateTime": "2026-08-12T01:18:00Z",
        "LastInferenceTime": "2026-08-12T01:20:36Z"
      }
    ]
  }
}
```

**状态枚举**：`Processing`（处理中，秒级）→ `Active`（可用）/ `Failed`（失败）

---

### 4.6 素材详情 / 删除

```http
GET    /v1/assets/:asset_id    # 详情（轮询状态用）
DELETE /v1/assets/:asset_id    # 删除（立即释放配额）
```

删除成功后配额立即释放，可循环使用（50 为存量上限）。

---

## 5. 完整对接流程（时序）

```
┌─────────┐     ① 查配额/默认组 ──▶  GET /v1/assets/quota ──▶ 拿到 group_id
│  你的   │
│  工具   │     ② 上传图片 URL ────▶  POST /v1/assets ──────▶ 拿到 asset_id
│ (二开/  │
│ 第三方) │     ③ 轮询状态 ────────▶  GET /v1/assets/:asset_id
│         │                            Processing → Active（约 2~5 秒）
│         │
│         │     ④ 生成视频 ────────▶  POST /v1/videos/generations
│         │                            images: ["asset://<asset_id>"]
│         │
│         │     ⑤ (可选) 删除素材 ──▶  DELETE /v1/assets/:asset_id
└─────────┘
```

---

## 6. 生成视频对接（配套）

素材入库后，用 `asset://` 地址代替普通 URL 生成视频：

```http
POST /v1/videos/generations
Content-Type: application/json
```

```json
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "图片1中的女性角色在森林中散步，阳光洒落，镜头缓缓推进，电影感",
  "images": ["asset://asset-20260812091800-287bf"],
  "duration": 5
}
```

⚠️ **关键点**：
- 必须用**顶层 `images` 数组**（不支持 content 数组，会被忽略报错）
- 多图参考时多个 `asset://` 地址并列，Prompt 中用「图片 1」「图片 2」指代
- 视频任务结果通过原视频任务查询接口获取（`/v1/videos/tasks/:task_id`）

---

## 7. 错误码与常见问题

| 错误 | HTTP | 说明与处理 |
|---|---|---|
| `PrivacyInformation` | 400 | **「疑似真人」误判**：图片被判定可能含真人肖像（防 Deepfake）。即使 AI 仿真图也会触发，属正常防护。→ 素材成功入库（Active）后即解除，务必用 `asset://` 引用 |
| `无效的令牌` | 401 | 令牌错误/过期，检查 Authorization 头 |
| `素材不存在或无权访问` | 404 | 素材不属于当前用户（用户隔离），或 ID 错误 |
| 请求过于频繁 | 429 | 触发限流，稍后重试（上传接口限频） |
| `server_error` | 502 | 上游（火山）异常，重试即可 |

**其他注意事项**：
- 素材有 7 天未使用自动回收机制（系统每日清理），长期使用的素材请定期调用以刷新 LastInferenceTime
- 每个用户只能看到/管理自己的素材，接口已按用户隔离
- 合规红线：禁止上传真实自然人肖像、未授权商标形象；仅限自有版权或 AI 生成的虚拟形象

---

## 8. 示例代码

### Python（requests）

```python
import requests
import time

BASE = "https://api.cxsee.com"
TOKEN = "<你的API令牌>"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# 1. 查询配额与默认组
quota = requests.get(f"{BASE}/v1/assets/quota", headers=HEADERS).json()["data"]
group_id = quota["group_id"]
print(f"配额: {quota['used']}/{quota['quota']}")

# 2. 上传素材
resp = requests.post(f"{BASE}/v1/assets", headers=HEADERS, json={
    "group_id": group_id,
    "url": "https://example.com/virtual-figure.png",
    "name": "角色A"
}).json()
asset_id = resp["Result"]["Id"]
print(f"已上传: {asset_id}")

# 3. 轮询状态至 Active
for _ in range(10):
    detail = requests.get(f"{BASE}/v1/assets/{asset_id}", headers=HEADERS).json()
    status = detail["Result"]["Status"]
    print(f"状态: {status}")
    if status in ("Active", "Failed"):
        break
    time.sleep(1)

# 4. 生成视频（asset:// 引用，不再触发疑似真人拦截）
if status == "Active":
    video = requests.post(f"{BASE}/v1/videos/generations", headers=HEADERS, json={
        "model": "doubao-seedance-2-0-260128",
        "prompt": "图片1中的角色在森林中散步，电影感",
        "images": [f"asset://{asset_id}"],
        "duration": 5
    }).json()
    print("视频任务:", video)
```

---

上一篇：模型自动智能路由下一篇：通义千问(qwen) 视频模型格式