素材库
- 把图片、视频、音频先入库，生成时用素材 ID 引用
- 同一路径
POST /doubao/api/，动作由查询参数Action选择 - 入库不计费，但素材要等审核通过（
Active）才能用于生成 - 真人人脸素材必须先入库审核，直接传 URL 会被拦截
认证
两种方式均可：
- 网关 API Token，与其他接口一致：
Authorization: Bearer YOUR_ARK_KEY - 火山 AK/SK 签名。为官方 SDK 写的脚本只需换掉 endpoint 即可复用，签名由网关用渠道配置的 AK/SK 代签。
请求时在请求头中添加：
Authorization: Bearer YOUR_ARK_KEYEither method works:
- The gateway API token, as with other endpoints:
Authorization: Bearer YOUR_ARK_KEY - Volcengine AK/SK signing. Scripts written for the official SDK only need their endpoint swapped to work; the gateway signs on your behalf using the AK/SK configured on the channel.
Add it to the request header:
Authorization: Bearer YOUR_ARK_KEY查询参数
要执行的动作。匹配时忽略大小写，转发时使用规范拼写。
可选值：CreateAsset、GetAsset、ListAssets、UpdateAsset、DeleteAsset、CreateAssetGroup、GetAssetGroup、ListAssetGroups、UpdateAssetGroup、DeleteAssetGroup。
方舟 API 版本，省略时使用 2024-01-01。
The action to perform. Matching is case-insensitive; forwarding uses the canonical spelling.
Values: CreateAsset, GetAsset, ListAssets, UpdateAsset, DeleteAsset, CreateAssetGroup, GetAssetGroup, ListAssetGroups, UpdateAssetGroup, DeleteAssetGroup.
The Ark API version; defaults to 2024-01-01 when omitted.
各动作的字段
请求体只读取所选 Action 规定的字段，其余字段忽略。
| Action | 字段 |
|---|---|
CreateAsset | GroupId、URL、AssetType、Name、Description、ProjectName |
GetAsset | Id、ProjectName |
ListAssets | Filter、PageNumber、PageSize、SortBy、SortOrder、ProjectName |
UpdateAsset | Id、Name、ProjectName |
DeleteAsset | Id、ProjectName |
CreateAssetGroup | Name、Description、GroupType、ProjectName |
GetAssetGroup | Id、ProjectName |
ListAssetGroups | Filter、NextToken、MaxResults、PageNumber、PageSize、SortBy、SortOrder、ProjectName |
UpdateAssetGroup | Id、Name、Description、ProjectName |
DeleteAssetGroup | Id、ProjectName |
The body is read only for the fields the chosen Action defines; other fields are ignored.
| Action | Fields |
|---|---|
CreateAsset | GroupId, URL, AssetType, Name, Description, ProjectName |
GetAsset | Id, ProjectName |
ListAssets | Filter, PageNumber, PageSize, SortBy, SortOrder, ProjectName |
UpdateAsset | Id, Name, ProjectName |
DeleteAsset | Id, ProjectName |
CreateAssetGroup | Name, Description, GroupType, ProjectName |
GetAssetGroup | Id, ProjectName |
ListAssetGroups | Filter, NextToken, MaxResults, PageNumber, PageSize, SortBy, SortOrder, ProjectName |
UpdateAssetGroup | Id, Name, Description, ProjectName |
DeleteAssetGroup | Id, ProjectName |
请求参数
素材或素材组的 ID。GetAsset、UpdateAsset、DeleteAsset、GetAssetGroup、UpdateAssetGroup、DeleteAssetGroup 必填。
新素材所属的素材组。CreateAsset 必填。
待入库素材的公网可访问地址，CreateAsset 必填。不接受 Base64 内容。
入库素材的媒体类型，CreateAsset 必填。取值 Image、Video、Audio。
显示名称，上限 64 字符。CreateAsset、UpdateAsset、CreateAssetGroup、UpdateAssetGroup 使用，列表动作可通过 Filter.Name 模糊搜索。
自由描述，上限 300 字符。CreateAssetGroup 与 UpdateAssetGroup 使用。
素材组类型。目前只接受 AIGC，CreateAssetGroup 会强制使用它：客户端传什么值都会在转发前被替换。
资源所属项目，默认 default。所有动作都可省略；素材与所属素材组的项目必须一致。
搜索过滤条件，ListAssets 与 ListAssetGroups 必填。
要搜索的素材组类型，取值 AIGC、LivenessFace。列表动作必填。
只返回这些素材组内的资源。
只返回这些处理状态的素材，仅 ListAssets 使用。取值 Active、Processing、Failed。
名称模糊匹配，上限 64 字符。
页码，从 1 开始。在 ListAssetGroups 上必须与 PageSize 同时出现，不能与 NextToken 或 MaxResults 混用。
每页数量，最大 100，与 PageNumber 成对使用。
上一次 ListAssetGroups 返回的游标。首次调用省略；不能与 PageNumber 或 PageSize 混用。
ListAssetGroups 游标模式的每页数量，默认 10，范围 1 到 100，与 NextToken 配合使用。
列表动作的排序字段。取值 CreateTime（默认）、UpdateTime、GroupId。
列表动作的排序方向。取值 Desc（默认）、Asc。
The asset or asset group ID. Required for GetAsset, UpdateAsset, DeleteAsset, GetAssetGroup, UpdateAssetGroup, and DeleteAssetGroup.
The asset group the new asset belongs to. Required for CreateAsset.
A publicly reachable URL for the asset to ingest; required for CreateAsset. Base64 content isn't accepted.
The media type of the asset; required for CreateAsset. Image, Video, or Audio.
A display name, up to 64 characters. Used by CreateAsset, UpdateAsset, CreateAssetGroup, and UpdateAssetGroup; list actions can fuzzy-search it via Filter.Name.
A free-form description, up to 300 characters. Used by CreateAssetGroup and UpdateAssetGroup.
The asset group type. Currently only AIGC is accepted; CreateAssetGroup forces it — whatever the client sends is replaced before forwarding.
The project the resource belongs to; defaults to default. Can be omitted on every action; an asset and its group must share the same project.
Search filters; required for ListAssets and ListAssetGroups.
The asset group type to search, AIGC or LivenessFace. Required for list actions.
Return only resources within these asset groups.
Return only assets in these processing states; ListAssets only. Active, Processing, or Failed.
Fuzzy name match, up to 64 characters.
Page number, starting at 1. On ListAssetGroups it must appear together with PageSize and can't be mixed with NextToken or MaxResults.
Items per page, at most 100, used together with PageNumber.
The cursor returned by the previous ListAssetGroups call. Omit on the first call; can't be mixed with PageNumber or PageSize.
Items per page for ListAssetGroups cursor mode; defaults to 10, range 1 to 100, used with NextToken.
The sort field for list actions: CreateTime (default), UpdateTime, or GroupId.
The sort direction for list actions: Desc (default) or Asc.
响应
上游信封原样返回，动作结果在 Result，动作失败记录在 ResponseMetadata.Error。HTTP 状态为 200 但 ResponseMetadata.Error 存在时，同样表示调用失败。
上游请求 ID，反馈问题时提供。
产生该响应的动作。
上游错误码，动作失败时出现。
上游错误信息。
新建或更新后的资源 ID。CreateAsset、CreateAssetGroup 与两个更新动作返回。
处理状态。取值 Active、Processing、Failed。只有 Active 的素材可被生成请求引用。
已入库素材的访问地址，有效期 12 小时，需要长期保存请自行转存。
列表动作的一页结果，没有匹配项时为空数组。
匹配的资源总数，列表动作在页码模式下返回。
The upstream envelope is returned as-is; action results are in Result and action failures are recorded in ResponseMetadata.Error. An HTTP 200 with ResponseMetadata.Error present also means the call failed.
The upstream request ID; include it when reporting problems.
The action that produced this response.
The upstream error code, present when the action failed.
The upstream error message.
The new or updated resource ID. Returned by CreateAsset, CreateAssetGroup, and both update actions.
The processing status: Active, Processing, or Failed. Only Active assets can be referenced by generation requests.
The access URL of an ingested asset, valid for 12 hours; copy it yourself if you need long-term storage.
One page of results for list actions; an empty array when nothing matches.
The total number of matching resources; list actions return it in page mode.
入库流程
CreateAsset 是异步接口，提交后素材处于 Processing，要轮询到 Active 才能用于生成。
- 调
CreateAssetGroup建组，拿到GroupId（也可复用已有组） - 调
CreateAsset提交素材公网地址，拿到素材Id - 轮询
GetAsset直到Status为Active - 在生成请求里引用该素材 ID
审核时长：图片通常数秒，视频与真人素材可能数分钟。
CreateAsset is async: after submission the asset is Processing, and you must poll until it's Active before using it for generation.
- Call
CreateAssetGroupto create a group and get theGroupId(an existing group can be reused) - Call
CreateAssetwith the asset's public URL and get the assetId - Poll
GetAssetuntilStatusisActive - Reference that asset ID in generation requests
Review time: images usually take seconds; video and real-person assets can take minutes.
使用限制
- 素材调用不预扣、不结算额度，每次调用在服务端日志中记录动作名
- 同一分组内最多只能有一个渠道选中素材库。有多个时网关直接拒绝，而不是随机路由：素材调用没有模型字段可供区分，随机转发会把素材写进别的库
- 真人人脸素材必须先入库审核，直接传 URL 会被内容审核拦截
- 素材入库后自动同步到全部可用渠道，多渠道路由时都能直接使用
- Asset calls don't reserve or settle balance; each call records its action name in the server log
- Only one channel per group may have the asset library selected. When several do, the gateway rejects the call outright rather than routing randomly: asset calls have no model field to distinguish them, so a random forward would write assets into someone else's library
- Assets showing real people's faces must be ingested and reviewed; passing a URL directly is intercepted by content moderation
- Once ingested, an asset is synced to all available channels, so multi-channel routing can use it directly
常见错误
| HTTP | 原因 |
|---|---|
| 400 | Action 缺失或不在白名单内 |
| 400 | 请求体不是 JSON 对象 |
| 400 | 分组内存在多个选中素材库的渠道 |
| 401 | Token 缺失或无效 |
| 502 | 上游调用失败，上游状态码与响应体一并透传 |
| HTTP | Cause |
|---|---|
| 400 | Action missing or not in the allowlist |
| 400 | The request body isn't a JSON object |
| 400 | More than one channel in the group has the asset library selected |
| 401 | Token missing or invalid |
| 502 | The upstream call failed; the upstream status code and response body are passed through |
错误码
For error response formats, status codes, and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.