API 文档 · 素材

素材上传

单文件、分片与 URL 导入。

素材先上传到平台，再在任务的 inputs 里通过 asset_id 引用，同一素材可在多个任务中重复使用。单个文件最大 2 GiB；上传会话在 1 小时内有效（见返回的 expires_at）。

单文件上传

文件不超过 100 MB 时，POST /v1/uploads 返回 method: "single" 与预签名的 upload_url。用 PUT 上传文件本体，并带上返回的 headers，然后调用 complete。

分片上传

更大的文件返回 method: "multipart"，并给出 part_size（通常为 16.0 MB）与 part_count：

调用 POST /v1/uploads/{id}/parts，传 { "part_numbers": [1, 2, …] }，每次最多 100 个，返回 { "parts": [{ "part_number": 1, "url": "…" }] }。
按顺序切片后 PUT 每个分片，记录响应头中的 ETag。
调用 complete，传 { "parts": [{ "part_number": 1, "etag": "…" }] }。

URL 导入

POST /v1/assets 传 source_url 代替 upload_id，平台从该地址拉取文件：仅支持 http / https 公网地址，文件不超过 250 MB，需在 60 秒内下载完成。只有拉取并保存成功后素材才会长期保存；拉取失败时状态变为 failed，status_reason 给出原因。

素材状态

status	含义
上传中	URL 导入：正在拉取文件
处理中	平台在探测格式、尺寸与时长并做内容审核
可用	可在任务中使用
需授权	声明为真人（real_person）的素材，需完成真人授权
失败	格式不符、拉取失败、内容审核未通过或校验值不一致，见 status_reason
删除中	已申请删除；仍被进行中的任务引用时，任务结束后清理

在素材变为 available 之前提交任务，会返回 422 asset_not_ready（可重试）。

# 1. 申请上传
curl https://cn-api.aitoken.tools/v1/uploads \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"hero.png","content_type":"image/png","size_bytes":1832211}'

# 2. 把文件 PUT 到返回的 upload_url（带上返回的 headers）
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @hero.png

# 3. 完成上传
curl -X POST https://cn-api.aitoken.tools/v1/uploads/upl_xxx/complete \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

# 4. 创建素材
curl https://cn-api.aitoken.tools/v1/assets \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_xxx","name":"hero"}'