七牛云 AI 大模型推理 API 支持上传虚拟人像素材，平台异步审核通过后，您可以在 Seedance 2.0 视频生成接口中通过 qasset:// URI 反复引用同一形象，无需每次重新上传。

素材功能核心特点

异步审核：提交素材立即拿到 qassetid 与初始 pending 状态，状态机为 pending → reviewing → approved/failed

分组管理：素材通过 Group 分组管理，绑定模型；您创建的第一个 Group 会成为默认分组，无需手动创建

跨任务复用：审核通过的素材通过 qasset://{qassetid} 在多个视频任务里反复引用

首期范围：仅支持虚拟人像（AIGC），仅在 Seedance 2.0 视频模型生效

整体三步流程：

上传素材 ──异步审核──▶ approved ──qasset:// 引用──▶ Seedance 视频生成

核心概念

概念	说明
Asset（素材）	单个虚拟人像，状态机 `pending → reviewing → approved/failed`
Group（分组）	素材的分组容器，绑定 `model`；您创建的第一个 Group 会成为默认分组
qassetid	用户可见的素材 ID，格式 `qasset-{uid}-{ts}`
qgroupid	用户可见的分组 ID，格式 `qgroup-{uid}-{ts}`
qasset://	在 Seedance 视频请求里嵌入素材的引用 URI，形如 `qasset://qasset-uid001-1716100100000000000`

接口说明

接入点

七牛云 AI 大模型推理 API 接入域名：

接入点: https://openai.qiniu.com

使用前提：获取 API KEY(API 密钥)

支持接口列表

接口	方法	说明
/v1/asset-groups	POST	创建素材分组（可选，多数场景不需要手动调用）
/v1/asset-groups	GET	分页查询当前用户的素材分组
/v1/asset-groups/:qgroupid	GET	查询单个分组详情
/v1/asset-groups/:qgroupid	PATCH	修改分组的 `name` / `description`
/v1/assets	POST	上传素材并提交审核（最常用入口）
/v1/assets	GET	分页查询当前用户的素材
/v1/assets/:qassetid	GET	查询单个素材详情，用于轮询审核状态

支持的模型

模型 ID	说明	状态
bytedance/doubao-seedance-2-0-260128	字节跳动豆包 Seedance 2.0，支持虚拟人像视频生成	✅ 已上线

注意：qasset:// 引用仅在 Seedance 2.0 系列模型生效。Sora / Kling / Vidu / Veo 等其他视频模型不支持。

快速上手：5 分钟跑通

下面这段最小闭环示例不显式建 Group，让平台自动处理：

响应：

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "公司虚拟形象",
  "status": "pending",
  "group_id": "qgroup-uid001-1716100000000000000",
  "created_at": 1716100100,
  "updated_at": 1716100100
}

跑通这三步后，请继续阅读下面的分场景详解。

分场景详解

1. 上传素材（默认 Group 模式，推荐新手）

接口：POST /v1/assets

Header 参数

参数名	类型	必填	说明
Authorization	string	是	API Key，格式：`Bearer YOUR_API_KEY`
Content-Type	string	是	固定值：`application/json`

Body 参数 (JSON)

参数名	类型	必填	默认值	说明
type	string	是	-	素材类型：`image`（图片）/ `video`（视频）/ `audio`（音频）
url	string	是	-	源文件 URL，必须公网可访问
name	string	是	-	素材展示名，1–200 字符
model	string	是	-	素材绑定的模型 ID，当前仅 `bytedance/doubao-seedance-2-0-260128`
group_id	string	否	-	关联的分组 `qgroupid`。留空则按当前账户下、相同 `type` 与 `model` 的默认 Group 自动选用；若没有则会自动新建。传入则该 Group 必须为可用状态且 `model` 与请求一致，否则返回 400

响应体说明

接口同步返回素材记录，初始状态为 pending，后续需轮询查询审核结果。

字段名	类型	说明
qassetid	string	用户可见素材 ID，格式 `qasset-{uid}-{ts}`
type	string	素材类型
name	string	展示名
model	string	绑定模型
status	string	任务状态，初始为 `pending`，详见状态流转
group_id	string	实际归属的分组 ID
fail_reason	string	仅 `status=failed` 时有值
created_at	integer	Unix 时间戳（秒）
updated_at	integer	Unix 时间戳（秒）

关键细节：默认 Group 的 4 种处理路径

不同的 group_id 处理路径，对用户的可观察行为差别较大：

场景	平台行为	用户感知
已有 active 默认 Group	直接复用，素材立刻进入 `reviewing`	提交后很快变 `reviewing`
没有任何默认 Group（首次上传）	异步创建一个 pending Group，并把素材挂在该 Group 下	素材会在 `pending` 停留较久，等 Group 激活后才会进入 `reviewing`
显式传 `group_id`，且该 Group `status=active`	直接复用	与第一种相同
显式传 `group_id`，但 Group 不存在 / 不属于本用户 / `status≠active`	返回 `400 invalid_request_error`	立即报错

新手提示：第一次调用 POST /v1/assets 看到素材长时间停在 pending，是平台在后台帮您建默认 Group，属正常现象，等待即可。后续上传会跳过这一步，进入 reviewing 会快很多。

示例

2. 主动管理 Group（高级场景）

何时需要主动建 Group：

想按业务线/项目把素材分组管理

已有素材想换 Group 归属

后续 model 扩展到多个值时，按模型分组

如果只是简单上传素材并复用，可跳过本节。

创建分组：`POST /v1/asset-groups`

参数名	类型	必填	默认值	说明
name	string	是	-	分组展示名，1–64 字符
description	string	否	-	分组描述，最长 300 字符
type	string	否	`aigc`	分组类型，首期仅支持 `aigc`（虚拟人像）
model	string	是	-	绑定的模型 ID

响应：

{
  "qgroupid": "qgroup-uid001-1716100000000000000",
  "type": "aigc",
  "name": "公司形象组",
  "description": "用于品牌视频的虚拟形象",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "pending",
  "is_default": true,
  "created_at": 1716100000,
  "updated_at": 1716100000
}

创建分组也是异步的：status=pending 立即返回，需轮询 GET /v1/asset-groups/{qgroupid} 直到 active 才能正常承接素材。
您创建的第一个 Group 会成为默认分组，后续手动新建的 Group 不会改变默认归属。后续上传素材若未指定 group_id，会一直落到该默认分组下。

查询单个分组：`GET /v1/asset-groups/:qgroupid`

修改分组：`PATCH /v1/asset-groups/:qgroupid`

只能修改 name 或 description，至少传一个；model 一旦创建无法修改。

列表查询：`GET /v1/asset-groups`

查询参数	类型	默认值	说明
page	integer	1	页码，从 1 开始
page_size	integer	20	每页大小，最大 100
status	string	-	过滤 `pending` / `active` / `failed`
type	string	-	过滤 `aigc`

3. 查询素材状态与轮询策略

接口：GET /v1/assets/:qassetid

状态流转

                   ┌──────────────────┐
                   │     pending      │  ← 默认 Group 异步创建中 / 已挂分组等待审核
                   └────────┬─────────┘
                            │  Group 激活后转入审核
                            ▼
                   ┌──────────────────┐
                   │    reviewing     │  ← 平台正在审核
                   └────────┬─────────┘
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
     ┌──────────────────┐        ┌──────────────────┐
     │     approved     │        │      failed      │
     │  ✅ 可被引用      │        │  ❌ 终态不可恢复  │
     └──────────────────┘        └──────────────────┘
                                  fail_reason 字段含具体原因

状态说明

状态值	说明
pending	已接收，等待审核（含默认 Group 创建中）
reviewing	平台正在审核
approved	审核通过，可被 `qasset://` 引用
failed	审核失败/提交失败/超时，终态不可恢复

响应示例

待处理状态

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "公司虚拟形象",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "pending",
  "group_id": "qgroup-uid001-1716100000000000000",
  "created_at": 1716100100,
  "updated_at": 1716100100
}

审核通过

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "公司虚拟形象",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "approved",
  "group_id": "qgroup-uid001-1716100000000000000",
  "created_at": 1716100100,
  "updated_at": 1716100250
}

审核失败

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "公司虚拟形象",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "failed",
  "group_id": "qgroup-uid001-1716100000000000000",
  "fail_reason": "image format not supported",
  "created_at": 1716100100,
  "updated_at": 1716100250
}

轮询建议

轮询间隔：5–10 秒一次，避免过于频繁

总超时：建议 10 分钟（首次上传含默认 Group 自动创建可能更长，可放宽到 15 分钟）

终态判断：只关注 approved 和 failed 两种终态，其他状态继续轮询

4. 查询素材列表：`GET /v1/assets`

查询参数	类型	默认值	说明
page	integer	1	页码，从 1 开始
page_size	integer	20	每页大小，最大 100
status	string	-	过滤 `pending` / `reviewing` / `approved` / `failed`
type	string	-	过滤 `image` / `video` / `audio`
group_id	string	-	按分组过滤，传入 `qgroup-{uid}-{ts}` 格式，必须属于当前用户

5. 在 Seedance 2.0 视频中引用素材 ⭐

qasset:// 引用通过两种协议接入 Seedance 2.0，两者任选其一。

协议 A：火山方舟原厂协议

接口：POST /v3/contents/generations/tasks

请求体使用 content 数组结构，每个节点带 type 和可选 role。image_url 节点的 url 字段处直接写 qasset://{qassetid}：

返回的 id 即视频任务 ID，使用 GET /v3/contents/generations/tasks/{id} 轮询任务状态。

同一份请求里可以拼接多个 image_url 节点引用多个素材，role 当前固定取 reference_image。

协议 B：fal 队列协议

路由汇总：

方法	路径	用途	是否支持 qasset://
POST	`/queue/bytedance/seedance-2.0/text-to-video`	文生视频（无图）	❌ 用不上
POST	`/queue/bytedance/seedance-2.0/image-to-video`	图生视频（首/尾帧）	✅
POST	`/queue/bytedance/seedance-2.0/reference-to-video`	多模态参考生视频（图/视频/音频）	✅
GET	`/bytedance/seedance-2.0/requests/:request_id/status`	查询任务状态	-
GET	`/bytedance/seedance-2.0/requests/:request_id`	获取任务结果	-

request_id 即创建任务时返回的 ID。

公共参数（三个 POST 接口都支持）：

参数名	类型	必填	默认值	说明
prompt	string	是	-	提示词，最长 2500 字符
resolution	string	否	720p	视频分辨率：`480p` / `720p` / `1080p`
duration	string	否	-	视频时长（秒），合法范围 `4`–`15`，默认遵循模型默认
aspect_ratio	string	否	auto	画面比例：`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `auto`
generate_audio	boolean	否	-	是否生成音轨
seed	int64	否	-	随机种子
end_user_id	string	否	-	终端用户标识
callback_url	string	否	-	回调 URL（也可通过 query 参数 `?fal_webhook=` 传入，query 优先级更高）

image-to-video 专属参数：

参数名	类型	必填	说明
image_url	string	是	起始帧 URL，支持 `qasset://`
end_image_url	string	否	结束帧 URL，支持 `qasset://`

reference-to-video 专属参数：

参数名	类型	必填	说明
image_urls	string[]	至少 image_urls 或 video_urls 之一非空	参考图片列表，最多 9 张，每个 URL 支持 `qasset://`
video_urls	string[]	同上	参考视频列表，最多 3 个，支持 `qasset://`
audio_urls	string[]	否	参考音频列表，最多 3 个，支持 `qasset://`；提供 `audio_urls` 时必须同时存在 image 或 video 参考

三类参考素材总数上限 12，超过返回 400。

引用规则

被引用素材必须 status=approved，否则视频任务会失败

素材必须属于当前 API Key 对应的用户，否则报权限错误

同一请求里可引用多个 qasset://，平台会在请求阶段自动完成解析，您只需写 qasset://{qassetid} 即可

普通公网 URL 仍然支持，qasset:// 与普通 URL 可在同一请求里混用

错误与故障排查

HTTP 状态码

HTTP 状态	错误类型	触发场景	处理建议
400	`invalid_request_error`	`type` 非法、`name` 超长、`group_id` 状态非 active、引用了未审核素材等	按错误信息修正请求体
401	`authentication_error`	API Key 缺失或无效	检查 `Authorization` 头部
403	`access_denied_error`	用户被封禁 / Agent 类型非 api	联系平台客服
404	`invalid_request_error`	qassetid / qgroupid 不存在或不属于当前用户	检查 ID 是否正确，是否使用了别人的 ID
500	`internal_server_error`	平台内部错误	重试，多次失败联系客服

错误响应统一结构：

{
  "error": {
    "type": "invalid_request_error",
    "message": "asset not found: qasset-xxx"
  }
}

素材审核失败常见原因

status=failed 时 fail_reason 字段会带出原因，常见场景：

内容审核未通过：人像包含敏感/违规元素

图片无法访问：url 字段在审核时已不可访问（已过期、私有、403 等）

图片格式或尺寸不符合要求：参考火山引擎方舟人像素材规范

审核超时：审核长时间未返回，平台会自动将素材标记为 failed

failed 是终态，无法恢复，需重新提交一个新素材。

常见问题

Q: 素材审核要多久？

A: 通常 1–3 分钟即可完成；首次上传时含"默认 Group 异步创建"步骤，可能 5–10 分钟。

Q: approved 后能改名/删除素材吗？

A: 当前版本不支持改名；删除后素材会从列表中移除并不再可被引用，但已经生成的视频任务不受影响。

Q: 同一张图能复用到多个 Group 吗？

A: 不能。一个 qassetid 只属于一个 Group。需要在多个分组下使用相同形象，请重复上传，每次会得到独立的 qassetid。

Q: 默认 Group 是怎么决定的？

A: 您创建的第一个 Group（无论是首次上传素材时由平台自动创建，还是显式调 POST /v1/asset-groups 创建）会成为默认分组，后续新建的 Group 不会改变默认归属。调 POST /v1/assets 不传 group_id 时，素材一直会落到该默认分组下。

Q: qasset:// 写错了会怎样？

A: 视频任务会在解析阶段失败，错误信息会指明哪个 qassetid 无效或非 approved。请使用 GET /v1/assets/{qassetid} 提前确认状态。

Q: Seedance 之外的视频模型能用 qasset:// 吗？

A: 不能。当前仅 bytedance/doubao-seedance-2-0-260128 支持 qasset:// 引用，Sora / Kling / Vidu / Veo 等其他视频模型不支持。

Q: API Key 怎么获取？

A: 见获取 API KEY。

参考文档

火山方舟 Seedance 2.0 官方文档

七牛云虚拟人像素材使用指南

素材功能核心特点#

核心概念#

接口说明#

接入点#

支持接口列表#

支持的模型#

快速上手：5 分钟跑通#

分场景详解#

1. 上传素材（默认 Group 模式，推荐新手）#

Header 参数#

Body 参数 (JSON)#

响应体说明#

关键细节：默认 Group 的 4 种处理路径#

示例#

2. 主动管理 Group（高级场景）#

创建分组：POST /v1/asset-groups#

查询单个分组：GET /v1/asset-groups/:qgroupid#

修改分组：PATCH /v1/asset-groups/:qgroupid#

列表查询：GET /v1/asset-groups#

3. 查询素材状态与轮询策略#

状态流转#

状态说明#

响应示例#

待处理状态#

审核通过#

审核失败#

轮询建议#

4. 查询素材列表：GET /v1/assets#

5. 在 Seedance 2.0 视频中引用素材 ⭐#

协议 A：火山方舟原厂协议#

协议 B：fal 队列协议#

引用规则#

错误与故障排查#

HTTP 状态码#

素材审核失败常见原因#

常见问题#

参考文档#