# 素材库
> 把图片、视频、音频先入库，生成时用素材 ID 引用
> 同一路径 `POST /doubao/api/`，动作由查询参数 `Action` 选择
> 入库不计费，但素材要等审核通过（`Active`）才能用于生成
> 真人人脸素材必须先入库审核，直接传 URL 会被拦截
`POST /doubao/api/`
## 认证
- `Authorization` (string / 必填) — 两种方式均可： - 网关 API Token，与其他接口一致：`Authorization: Bearer YOUR_ARK_KEY` - 火山 AK/SK 签名。为官方 SDK 写的脚本只需换掉 endpoint 即可复用，签名由网关用渠道配置的 AK/SK 代签。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_ARK_KEY ```
## 查询参数
- `Action` (string / 必填) — 要执行的动作。匹配时忽略大小写，转发时使用规范拼写。 可选值：`CreateAsset`、`GetAsset`、`ListAssets`、`UpdateAsset`、`DeleteAsset`、`CreateAssetGroup`、`GetAssetGroup`、`ListAssetGroups`、`UpdateAssetGroup`、`DeleteAssetGroup`。
- `Version` (string / 可选) — 方舟 API 版本，省略时使用 `2024-01-01`。
## 各动作的字段
请求体只读取所选 `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` |
## 请求参数
- `Id` (string / 可选) — 素材或素材组的 ID。`GetAsset`、`UpdateAsset`、`DeleteAsset`、`GetAssetGroup`、`UpdateAssetGroup`、`DeleteAssetGroup` 必填。
- `GroupId` (string / 可选) — 新素材所属的素材组。`CreateAsset` 必填。
- `URL` (string / 可选) — 待入库素材的公网可访问地址，`CreateAsset` 必填。不接受 Base64 内容。
- `AssetType` (string / 可选) — 入库素材的媒体类型，`CreateAsset` 必填。取值 `Image`、`Video`、`Audio`。
- `Name` (string / 可选) — 显示名称，上限 64 字符。`CreateAsset`、`UpdateAsset`、`CreateAssetGroup`、`UpdateAssetGroup` 使用，列表动作可通过 `Filter.Name` 模糊搜索。
- `Description` (string / 可选) — 自由描述，上限 300 字符。`CreateAssetGroup` 与 `UpdateAssetGroup` 使用。
- `GroupType` (string / 可选) — 素材组类型。目前只接受 `AIGC`，`CreateAssetGroup` 会强制使用它：客户端传什么值都会在转发前被替换。
- `ProjectName` (string / 可选) — 资源所属项目，默认 `default`。所有动作都可省略；素材与所属素材组的项目必须一致。
- `Filter` (object / 可选) — 搜索过滤条件，`ListAssets` 与 `ListAssetGroups` 必填。
- `Filter.GroupType` (string / 可选) — 要搜索的素材组类型，取值 `AIGC`、`LivenessFace`。列表动作必填。
- `Filter.GroupIds` (array / 可选) — 只返回这些素材组内的资源。
- `Filter.Statuses` (array / 可选) — 只返回这些处理状态的素材，仅 `ListAssets` 使用。取值 `Active`、`Processing`、`Failed`。
- `Filter.Name` (string / 可选) — 名称模糊匹配，上限 64 字符。
- `PageNumber` (integer / 可选) — 页码，从 `1` 开始。在 `ListAssetGroups` 上必须与 `PageSize` 同时出现，不能与 `NextToken` 或 `MaxResults` 混用。
- `PageSize` (integer / 可选) — 每页数量，最大 `100`，与 `PageNumber` 成对使用。
- `NextToken` (string / 可选) — 上一次 `ListAssetGroups` 返回的游标。首次调用省略；不能与 `PageNumber` 或 `PageSize` 混用。
- `MaxResults` (integer / 可选) — `ListAssetGroups` 游标模式的每页数量，默认 `10`，范围 1 到 100，与 `NextToken` 配合使用。
- `SortBy` (string / 可选) — 列表动作的排序字段。取值 `CreateTime`（默认）、`UpdateTime`、`GroupId`。
- `SortOrder` (string / 可选) — 列表动作的排序方向。取值 `Desc`（默认）、`Asc`。
## 响应
上游信封原样返回，动作结果在 `Result`，动作失败记录在 `ResponseMetadata.Error`。HTTP 状态为 200 但 `ResponseMetadata.Error` 存在时，同样表示调用失败。
- `ResponseMetadata.RequestId` (string) — 上游请求 ID，反馈问题时提供。
- `ResponseMetadata.Action` (string) — 产生该响应的动作。
- `ResponseMetadata.Error.Code` (string) — 上游错误码，动作失败时出现。
- `ResponseMetadata.Error.Message` (string) — 上游错误信息。
- `Result.Id` (string) — 新建或更新后的资源 ID。`CreateAsset`、`CreateAssetGroup` 与两个更新动作返回。
- `Result.Status` (string) — 处理状态。取值 `Active`、`Processing`、`Failed`。只有 `Active` 的素材可被生成请求引用。
- `Result.URL` (string) — 已入库素材的访问地址，有效期 12 小时，需要长期保存请自行转存。
- `Result.Items` (array) — 列表动作的一页结果，没有匹配项时为空数组。
- `Result.TotalCount` (integer) — 匹配的资源总数，列表动作在页码模式下返回。
## 入库流程
`CreateAsset` 是异步接口，提交后素材处于 `Processing`，要轮询到 `Active` 才能用于生成。
1. 调 `CreateAssetGroup` 建组，拿到 `GroupId`（也可复用已有组）
2. 调 `CreateAsset` 提交素材公网地址，拿到素材 `Id`
3. 轮询 `GetAsset` 直到 `Status` 为 `Active`
4. 在生成请求里引用该素材 ID
审核时长：图片通常数秒，视频与真人素材可能数分钟。
## 使用限制
- 素材调用不预扣、不结算额度，每次调用在服务端日志中记录动作名
- 同一分组内最多只能有一个渠道选中素材库。有多个时网关直接拒绝，而不是随机路由：素材调用没有模型字段可供区分，随机转发会把素材写进别的库
- 真人人脸素材必须先入库审核，直接传 URL 会被内容审核拦截
- 素材入库后自动同步到全部可用渠道，多渠道路由时都能直接使用
## 常见错误
| HTTP | 原因 |
|---|---|
| 400 | `Action` 缺失或不在白名单内 |
| 400 | 请求体不是 JSON 对象 |
| 400 | 分组内存在多个选中素材库的渠道 |
| 401 | Token 缺失或无效 |
| 502 | 上游调用失败，上游状态码与响应体一并透传 |
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 创建素材组
### 提交素材
### 查询素材状态
### 列出可用素材
**创建素材组{CreateAssetGroup}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=CreateAssetGroup&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "Name": "protagonists",
  "Description": "用作视频参考的人物素材",
  "GroupType": "AIGC",
  "ProjectName": "default"
}'
```
**创建素材组{CreateAssetGroup}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=CreateAssetGroup&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "Name": "protagonists",
  "Description": "用作视频参考的人物素材",
  "GroupType": "AIGC",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**创建素材组{CreateAssetGroup}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=CreateAssetGroup&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "Name": "protagonists",
  "Description": "用作视频参考的人物素材",
  "GroupType": "AIGC",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**提交素材{CreateAsset}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=CreateAsset&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "GroupId": "group-2026**********-*****",
  "URL": "https://example.com/portrait.png",
  "AssetType": "Image",
  "Name": "protagonist",
  "ProjectName": "default"
}'
```
**提交素材{CreateAsset}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=CreateAsset&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "GroupId": "group-2026**********-*****",
  "URL": "https://example.com/portrait.png",
  "AssetType": "Image",
  "Name": "protagonist",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**提交素材{CreateAsset}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=CreateAsset&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "GroupId": "group-2026**********-*****",
  "URL": "https://example.com/portrait.png",
  "AssetType": "Image",
  "Name": "protagonist",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**查询素材{GetAsset}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=GetAsset&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "Id": "Asset-2026**********-*****",
  "ProjectName": "default"
}'
```
**查询素材{GetAsset}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=GetAsset&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "Id": "Asset-2026**********-*****",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**查询素材{GetAsset}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=GetAsset&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "Id": "Asset-2026**********-*****",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**素材列表{ListAssets}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=ListAssets&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "Filter": {
    "GroupType": "AIGC",
    "GroupIds": [
      "group-2026**********-*****"
    ],
    "Statuses": [
      "Active"
    ]
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}'
```
**素材列表{ListAssets}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=ListAssets&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "Filter": {
    "GroupType": "AIGC",
    "GroupIds": [
      "group-2026**********-*****"
    ],
    "Statuses": [
      "Active"
    ]
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**素材列表{ListAssets}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=ListAssets&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "Filter": {
    "GroupType": "AIGC",
    "GroupIds": [
      "group-2026**********-*****"
    ],
    "Statuses": [
      "Active"
    ]
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**更新素材{UpdateAsset}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=UpdateAsset&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "Id": "Asset-2026**********-*****",
  "Name": "protagonist-front",
  "ProjectName": "default"
}'
```
**更新素材{UpdateAsset}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=UpdateAsset&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "Id": "Asset-2026**********-*****",
  "Name": "protagonist-front",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**更新素材{UpdateAsset}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=UpdateAsset&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "Id": "Asset-2026**********-*****",
  "Name": "protagonist-front",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**删除素材{DeleteAsset}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=DeleteAsset&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "Id": "Asset-2026**********-*****",
  "ProjectName": "default"
}'
```
**删除素材{DeleteAsset}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=DeleteAsset&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "Id": "Asset-2026**********-*****",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**删除素材{DeleteAsset}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=DeleteAsset&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "Id": "Asset-2026**********-*****",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**素材组列表{ListAssetGroups}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/doubao/api/?Action=ListAssetGroups&Version=2024-01-01' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "Filter": {
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}'
```
**素材组列表{ListAssetGroups}::Python**
```
import requests
url = "https://ark.oairoute.com/doubao/api/?Action=ListAssetGroups&Version=2024-01-01"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
  "Filter": {
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**素材组列表{ListAssetGroups}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/doubao/api/?Action=ListAssetGroups&Version=2024-01-01", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "Filter": {
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}),
});
console.log(await res.json());
```
**200 创建素材组{CreateAssetGroup}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-2026**********-*****"
  }
}
```
**200 提交素材{CreateAsset}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "Asset-2026**********-*****"
  }
}
```
**200 查询素材{GetAsset}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "Asset-2026**********-*****",
    "Name": "protagonist",
    "URL": "https://example.com/asset-url",
    "AssetType": "Image",
    "GroupId": "group-2026**********-*****",
    "Status": "Active",
    "Error": {
      "Code": "",
      "Message": ""
    },
    "CreateTime": "2026-03-28T00:00:00Z",
    "UpdateTime": "2026-03-28T00:00:00Z",
    "ProjectName": "default"
  }
}
```
**200 素材列表{ListAssets}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "Asset-2026**********-*****",
        "Name": "protagonist",
        "URL": "https://example.com/asset-url",
        "GroupId": "group-2026**********-*****",
        "AssetType": "Image",
        "Status": "Active",
        "Error": {
          "Code": "",
          "Message": ""
        },
        "ProjectName": "default",
        "CreateTime": "2026-03-28T00:00:00Z",
        "UpdateTime": "2026-03-28T00:00:00Z"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 10
  }
}
```
**200 更新素材{UpdateAsset}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "UpdateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "Asset-2026**********-*****"
  }
}
```
**200 删除素材{DeleteAsset}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "DeleteAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}
```
**200 素材组列表{ListAssetGroups}**
```
{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "group-2026**********-*****",
        "Name": "protagonists",
        "Description": "用作视频参考的人物素材",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-03-28T00:00:00Z",
        "UpdateTime": "2026-03-28T00:00:00Z"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 10
  }
}
```