素材库与 asset:// 引用
上传素材后，在支持的图像生成和视频任务字段中使用 asset://<id>；具体处理随模型与接口而定。
上传流程
在控制台“素材库”页面或通过控制台 API 创建上传：POST /api/v1/assets 返回预签名地址 → 浏览器 / 客户端直传对象存储 → POST /api/v1/assets/uploads/{upload_id}/complete 完成校验。素材归属于当前用户，跨用户不可见。
网页参考图选择器接受最大 100 MiB 的 JPG、PNG、WebP 原图；超过 10 MiB 会先在浏览器优化到上游安全大小后上传。文本/视觉对话也可选择最大 100 MiB 原图，发送前会优化成单次请求可承受的内联数据；较大的 GIF 只使用静态首帧。图像生成 API 中的素材引用仍为单张不超过 10 MiB、合计不超过 20 MiB；SDK 与直接 API 调用不会替调用者自动优化原图。视频最大 200 MiB；其他类型以控制台提示为准。
在请求中引用
{"type": "image_url", "image_url": {"url": "asset://1024"}, "role": "reference_image"}- 图像生成的 image 字段会先核验素材归属、实际字节和格式，再转换为上游支持的 Base64；不会把 LINK42 的私有 asset:// 编号直接发给火山。视频任务按账号能力使用上游素材库或直接图片输入。
- 一把密钥能引用哪些素材，由它的素材访问范围决定，详见“鉴权、限流与幂等”页的“密钥的素材访问范围”。
用 API Key 管理素材
POST/v1/assets
服务端程序可以直接用 API Key 调用网关的 /v1/assets 接口上传和管理素材。鉴权方式与模型调用相同（Authorization: Bearer 或 x-api-key 头），同样检查密钥状态和 IP 白名单，不接受浏览器会话。官方 SDK 的 assets 方法封装的就是这组接口。
上传分三步：先 POST /v1/assets 预留上传，返回 asset（此时 status 为 pending）、upload_id 和 upload；再在 upload.expires_at 之前（默认 15 分钟）把文件 PUT 到 upload.url，原样带上 upload.headers 里的每个请求头，不要带 LINK42 密钥；最后 POST /v1/assets/uploads/{upload_id}/complete。平台核对文件的大小、类型和实际内容，通过后素材变为 active，返回体里的 reference（asset://<id>）就可以在请求里引用。
预留上传可以带 Idempotency-Key 头，用同一个键重复提交会返回首次的预留，响应带 Idempotency-Replayed: true。素材接口每个账户每分钟最多 120 次（密钥的 RPM 限额更低时以 RPM 为准），超出返回 429 rate_limited 并带 Retry-After。
| 接口 | 说明 |
|---|---|
| POST /v1/assets | 预留上传，成功返回 201。请求体：name（1–160 个字符）、type（image / video / audio）、content_type（须与 type 匹配）、size_bytes（文件的字节数）。单个文件的大小上限按类型和分组设定，超出返回 422 asset_too_large。 |
| PUT upload.url | 把文件直传到存储。请求头取自 upload.headers，不带 LINK42 密钥。 |
| POST /v1/assets/uploads/{upload_id}/complete | 确认上传，返回 active 的素材。文件还没上传返回 409 asset_object_missing，超过 expires_at 返回 409 asset_upload_expired，大小或类型与预留不符返回 422 asset_object_mismatch，实际内容与声明的类型不符返回 422 asset_content_mismatch。 |
| GET /v1/assets | 按创建时间倒序分页列出素材。查询参数：page、page_size（默认 100，最大 200）、type、status（pending / active / failed）、q（按名称模糊匹配，最多 100 个字符）。返回 {list, total, page, page_size}。 |
| GET /v1/assets/{id} | 读取一个素材。 |
| GET /v1/assets/{id}/download | 返回 {url}：5 分钟内有效的下载链接，只适用于 active 素材。不要保存或公开这个链接。 |
| DELETE /v1/assets/{id} | 删除素材，成功返回 204。仍被任务引用的素材返回 409 asset_in_use。 |
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 素材编号。 |
| name | string | 素材名称。 |
| type | string | image、video 或 audio。 |
| status | string | pending（等待上传或确认）、active（可以使用）或 failed。 |
| content_type | string | 文件的 MIME 类型，例如 image/png。 |
| size_bytes | integer | 文件字节数。 |
| ref_count | integer | 引用这个素材的任务数；大于 0 时不能删除。 |
| reference | string | asset://<id>，在请求里引用素材时使用。 |
| created_at | string | 创建时间。 |
| ready_at | string | 确认完成的时间；尚未完成时为 null。 |
curl https://www.link42.ai/v1/assets \
-H "Authorization: Bearer $LINK42_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "reference.png", "type": "image", "content_type": "image/png", "size_bytes": 482913}'
# 把文件 PUT 到返回的 upload.url；两个请求头取自 upload.headers，不带 LINK42 密钥
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
-H "x-amz-meta-onerelay-upload-id: $UPLOAD_ID" \
--data-binary @reference.png
# 确认上传；返回体里的 reference 就是 asset://<id>
curl -X POST https://www.link42.ai/v1/assets/uploads/$UPLOAD_ID/complete \
-H "Authorization: Bearer $LINK42_API_KEY"访问范围对素材接口的影响
密钥的素材访问范围同样决定它能通过 /v1/assets 查看和操作哪些素材。通过这组接口上传的素材记在上传它的密钥名下；在控制台上传的素材不属于任何密钥。
| 操作 | own | all | none |
|---|---|---|---|
| 预留上传 | 可以 | 可以 | 403 asset_access_denied |
| complete | 只能确认这把密钥预留的上传，其他上传返回 404 | 账户下任意上传 | 403 asset_access_denied |
| 列表、详情、下载 | 这把密钥上传的素材和控制台上传的素材；其他密钥上传的素材不出现在列表里，按 id 访问返回 404 | 账户下全部素材 | 403 asset_access_denied |
| 删除 | 只能删除这把密钥上传的素材；控制台上传的素材返回 403 asset_not_deletable，其他密钥上传的素材返回 404 | 账户下全部素材 | 403 asset_access_denied |
- own 密钥看不到的素材一律返回 404，和素材不存在时相同，无法借此探测其他密钥上传了什么。
- 控制台上传的素材属于账户本身：own 密钥可以查看、下载和引用，但删除要在控制台进行，或使用访问范围为 all 的密钥。