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

# 素材库

> /v1/assets：先上传图片、视频、音频，再在生成请求里用 asset:// 引用。

素材库用来保存你反复使用的参考素材。上传一次得到素材 ID，之后在任何生成请求里，把原本填图片、视频、音频链接的位置换成 `asset://` 加素材 ID 即可，不用自己托管文件或维护公网链接。

* 素材只有你自己的密钥能看到和引用。
* 文件会一直保存，直到你删除。
* 上传和存储免费，只按生成计费。
* 控制台的 [素材库](https://token.poryf.com/assets) 页面和在线使用里的「从素材库选择」用的是同一个素材库：网页上传的素材可以在 API 里引用，API 上传的也能在网页里看到和使用。

## 上传素材

`POST /v1/assets`，用 `multipart/form-data` 提交：

**file** `file` *required*

素材文件。格式以文件内容为准：图片支持 PNG、JPEG、WebP（不超过 30 MB），视频支持 MP4（不超过 50 MB），音频支持 MP3、WAV（不超过 15 MB）。

**name** `string`

素材名称，不超过 100 个字符，方便你自己辨认。

```bash theme={null}
curl https://token.poryf.com/v1/assets \
  -H "Authorization: Bearer $API_KEY" \
  -F file=@person.png \
  -F name="主角正脸"
```

```json theme={null}
{
  "id": "ast_k3m5q7s2u4w6y2a3c5e7g2j4",
  "object": "asset",
  "uri": "asset://ast_k3m5q7s2u4w6y2a3c5e7g2j4",
  "type": "image",
  "category": "general",
  "name": "主角正脸",
  "mime_type": "image/png",
  "bytes": 482113,
  "width": 1062,
  "height": 1432,
  "status": "ready",
  "created_at": 1792113600,
  "url": "https://…（24 小时有效的预览链接）"
}
```

同一个文件重复上传，会直接返回已有的素材。每个账号最多保存 500 个素材、合计 2 GB。

## 人像素材（真人照片）

带真人人脸的照片直接用链接传给 Seedance，会被上游审核拦截（任务失败，报错 `InputImageSensitiveContentDetected.PrivacyInformation`，费用自动退回）。真人照片请作为**人像素材**上传，再用 `asset://` 引用：

```bash theme={null}
curl https://token.poryf.com/v1/assets \
  -H "Authorization: Bearer $API_KEY" \
  -F file=@me.jpg \
  -F category=portrait \
  -F consent=true
```

**category** `string` (default: general)

`general`（普通素材）或 `portrait`（人像素材）。人像素材只支持 PNG、JPEG、WebP 图片。

**consent** `string`

上传人像素材时必须传 `true`，表示你确认：照片中的人物是你本人，或你已取得其本人对该照片用于 AI 视频生成的单独同意，且不会用于冒充他人、虚假信息或其他违法用途。平台会记录本次确认的时间与来源 IP。

* 上传时平台会先把照片提交给视频服务方做人像审核，通常 10 秒左右完成，服务方繁忙时可能要几分钟。审核通过后 `status` 为 `ready`；上传最多等 20 秒，还没完成时返回 `processing`，可以用 `GET /v1/assets/{id}` 查看进度。
* 引用还在 `processing` 的人像素材时，生成请求最多等 30 秒；仍未完成会返回 409（`asset_not_ready`），不会扣费，请过几分钟再试。
* 照片未通过审核时上传返回 400，素材不会保存，请换一张清晰的单人正脸照片。
* 上传时返回 `processing`、之后才审核失败的照片，`status` 会变为 `failed`。引用它的生成请求返回 400（`asset_rejected`），不会扣费。请删除这个素材，换一张照片重新上传。
* 人像素材目前只能用于 Seedance 系列模型。其他模型引用人像素材时，请求会因为没有可用渠道而失败。
* 删除人像素材时，平台会同时删除服务方那边的副本。服务方还在处理这张照片时，删除会返回 202（`status` 为 `deleting`）：素材立即不能再引用，平台会在后台继续完成删除。

## 在生成请求里引用

把 `uri` 填到原本放链接的位置。以 Seedance 多模态参考为例：

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "参考图片1中的人物，按照视频1的动作在城市街头跳舞",
    "seconds": 8,
    "metadata": {
      "resolution": "720p",
      "content": [
        {"type": "image_url", "image_url": {"url": "asset://ast_k3m5q7s2u4w6y2a3c5e7g2j4"}, "role": "reference_image"},
        {"type": "video_url", "video_url": {"url": "asset://ast_p2r4t6v2x4z6b3d5f7h2k4m6"}, "role": "reference_video"}
      ]
    }
  }'
```

图片生成、图片编辑和对话里的图片链接也可以这样引用。只有完整等于 `asset://ast_…` 的字段值会被识别，写在提示词文字里的、或者用作字段名的不会被替换。

引用只在 JSON 请求体（`Content-Type: application/json`）里生效。`multipart/form-data` 或表单请求里出现 `asset://` 会直接返回 400；Responses WebSocket 暂不支持。请改用 JSON 请求，或直接传文件链接。

> [!WARNING]
>
> 引用不存在、已删除或不属于当前账号的素材时，请求会返回 400（`asset_not_found`），不会产生费用。

## 查看和管理

| 接口 | 说明 |
| - | - |
| `GET /v1/assets` | 列出素材，新的在前。参数：`type`（`image` / `video` / `audio`）、`category`（`general` / `portrait`）、`limit`（1～100，默认 20）、`after`（上一页最后一个素材的 `id`）。响应里 `has_more` 表示是否还有下一页 |
| `GET /v1/assets/{id}` | 查看单个素材 |
| `PATCH /v1/assets/{id}` | 改名，JSON 请求体 `{"name": "新名称"}` |
| `DELETE /v1/assets/{id}` | 删除素材和文件，之后引用它的请求会返回 400 |

```bash theme={null}
curl 'https://token.poryf.com/v1/assets?type=image&limit=20' \
  -H "Authorization: Bearer $API_KEY"
```

## 常见错误

| 状态码 | `code` | 原因 |
| - | - | - |
| 400 | `invalid_asset` | 格式不支持、文件超过大小限制，或素材数量、总容量已满 |
| 400 | `asset_not_found` | 生成请求里引用的素材不存在或不属于你 |
| 400 | `asset_rejected` | 引用的人像素材没有通过审核，请删除后换一张照片 |
| 409 | `asset_not_ready` | 引用的人像素材还在审核中，请过几分钟再试 |
| 503 | `asset_unavailable` | 暂时没有可以使用人像素材的渠道，请稍后再试 |
| 404 | `asset_not_found` | 查询、改名或删除的素材不存在 |
| 429 | — | 上传太频繁，每个账号每分钟最多上传 10 个 |


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