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"}'