資產(Assets)

通用資訊

• Base URL：https://api.routeapi.ai
• 認證：Authorization: Bearer $ROUTEAPI_KEY，使用 sk- 開頭的 API Key（在控制台 API Keys 頁面建立）。rat_ 開頭的管理金鑰不能呼叫模型。
• 錯誤格式：這些端點上 RouteAPI 自身的錯誤使用 {"error": "..."} 或 {"error": "...", "code": "..."}；被共用認證或限流中介層拒絕的請求則可能回傳 {"error": {"message": "...", "type": "error", "code": "..."}}。上游狀態碼與回應主體原樣透傳。詳見下文限制與錯誤與常見錯誤。

資產 API 用於儲存參考素材——圖像、影片、音訊——供 Seedance 影片模型作為輸入使用。素材只需新增一次，等上游資產服務處理完成後，即可在影片生成請求中以 asset://<asset_id> 引用它，不必每次都傳入同一個公開 URL。

這是管理類 API，不是生成類 API。RouteAPI 會用你的 API Key 完成呼叫認證，轉發到上游資產服務，並回傳上游的回應。這些端點上的呼叫不會按模型用量計費。它們也不在 OpenAI SDK 的涵蓋範圍內，因此請使用原生 HTTP，而不是 SDK 用戶端。

請求與回應主體原樣轉發

RouteAPI 不會重塑資產請求主體。除了下方的容量限制與特殊處理之外，請求與回應主體 都會原樣透傳，因此這裡顯示的欄位集合就是上游契約。請勿把確切的回應欄位集合 視為固定不變。

工作流程

1. 建立資產組：POST /v1/asset-groups。
2. 新增資產到該組：POST /v1/assets，傳入可從公開網路下載的 URL。
3. 輪詢資產：GET /v1/assets/{assetID}，直到狀態變成 Active。處理是非同步的。
4. 引用資產：在 POST /v1/video/generations 請求的 metadata.content 中以 asset://<asset_id> 引用它。參見在 Seedance 請求中使用資產和Seedance。
5. 照常輪詢影片任務。以資產為基礎的影片請求只會向上游送出一次，不會重試，也不會故障轉移到其他渠道。

端點

方法	路徑	用途	是否分配資產空間
POST	/v1/asset-groups	建立資產組	是
GET	/v1/asset-groups	列出資產組	否
GET	/v1/asset-groups/{groupID}	取得單一資產組	否
DELETE	/v1/asset-groups/{groupID}	刪除資產組	否
PUT	/v1/asset-groups/{groupID}	重新命名資產組	否
POST	/v1/assets	將資產新增至資產組	是
GET	/v1/assets	列出資產組中的資產	否
GET	/v1/assets/{assetID}	取得單一資產（用於輪詢）	否
DELETE	/v1/assets/{assetID}	刪除資產	否
PUT	/v1/assets/{assetID}	重新命名資產	否
POST	/v1/assets/verify-sessions	建立真人核驗工作階段	是
GET	/v1/assets/verify-sessions/{sessionID}	取得核驗工作階段	否

認證方式

在標準標頭中傳入 Model API Key：

Authorization: Bearer sk-your-routeapi-key

該 Key 代表 RouteAPI 帳戶。資產按帳戶隔離：同一帳戶下的每個 API Key 看到的是相同的資產組、資產與核驗工作階段，其他帳戶則看不到它們。該 Key 絕不會被送往上游——RouteAPI 會代替你使用獨立的上游憑證。

首次使用與資產池金鑰

每個帳戶會綁定一個上游憑證，資產服務用它來隔離該帳戶的素材。帳戶第一次呼叫建立類端點時會自動指派：

• POST /v1/asset-groups
• POST /v1/assets
• POST /v1/assets/verify-sessions

一旦指派，該綁定對帳戶即為永久有效，後續每次呼叫都會重複使用，包括引用 asset:// 資產的影片請求。

讀取與刪除類端點從不分配。綁定建立之前：

呼叫	回應
GET /v1/asset-groups	200，空列表：{"total": 0, "asset_groups": []}
其他任何 GET 或 DELETE	404，{"error": "not found"}

也就是說，空資產組列表對新帳戶而言是正常結果；而首次使用之前對某個具體資產或資產組回傳 404，含義是「該帳戶尚無資產空間」，而不是「ID 有誤」。

資產組到憑證的路由屬於服務端配置細節。如果所屬分組沒有設定資產渠道，第一次建立類呼叫會以 503 asset_pool_exhausted 或 503 asset_pool_misconfigured 失敗，而不是分配憑證。請稍後重試；若持續發生，請聯絡客服。

故障的金鑰將持續停用

如果上游以 401 拒絕你的憑證，RouteAPI 會把該綁定標記為故障，並回傳 503 asset_key_unavailable。之後所有資產呼叫——以及每個引用資產的影片請求—— 都會持續回傳這個錯誤碼，直到管理員還原綁定。因此在生產環境依賴這條路徑之前， 請先在測試環境驗證。

資產組

建立資產組

POST /v1/asset-groups

curl https://api.routeapi.ai/v1/asset-groups \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-refs",
    "description": "Reference material for product videos"
  }'

欄位	類型	必填	說明
name	string	是	資產組名稱
description	string	否	資產組說明

回應：

{
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "name": "product-refs",
  "project_name": "default",
  "status": "active"
}

請保留 asset_group_id：新增資產時必須用到它。

列出資產組

GET /v1/asset-groups

curl "https://api.routeapi.ai/v1/asset-groups?page=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

page、page_size 等分頁參數會原樣轉發；上游服務的預設值與單頁上限同樣適用。

{
  "total": 1,
  "asset_groups": [
    {
      "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
      "group_type": "AIGC",
      "project_name": "default",
      "session_id": "",
      "status": "active",
      "created_at": 1792050332,
      "updated_at": 1792050332
    }
  ]
}

session_id 只有在透過真人核驗建立的資產組中才有值。已核驗真人的資產組，其 group_type 為 LivenessFace；一般資產組則為 AIGC。

取得單一資產組

curl https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

上游的詳情回應可能回傳空的 status 字串。需要判斷資產組是否可用時，請改用列表回應或建立回應中的值。

刪除資產組

curl -X DELETE https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

刪除後無法復原。

重新命名資產組

curl -X PUT https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_group_name"}'

{ "name": "new_group_name", "updated": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

資產

新增資產

POST /v1/assets

每次請求新增一個資產。請傳入所屬資產組、名稱，以及且僅一個來源 URL。

欄位	類型	必填	說明
asset_group_id	string	是	資產所屬的資產組
asset_name	string	是	僅用於查詢的名稱；不影響生成
image_url	string	三選一	圖像的公開 URL
video_url	string	三選一	影片的公開 URL
audio_url	string	三選一	音訊檔案的公開 URL
asset_type	string	否	Image、Video 或 Audio；省略時依 URL 欄位推斷
description	string	否	資產說明

image_url、video_url、audio_url 必須且只能傳入一個；傳入零個或多個時，上游服務會拒絕請求。該 URL 必須能在公開網際網路上下載，無需認證或額外標頭。不支援 Base64 內容與內網位址，且在處理完成前該 URL 必須保持可存取。

curl https://api.routeapi.ai/v1/assets \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
    "asset_name": "product-front",
    "image_url": "https://cdn.example.com/product-front.jpg"
  }'

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "asset_name": "product-front",
  "asset_type": "Image",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "status": "Processing"
}

建立成功只代表請求已被接受，不代表資產已可使用。asset_uri 才是影片請求中應使用的形式。

資產狀態

狀態	含義	建議動作
Processing	仍在擷取處理中	繼續輪詢
Active	可以使用	在影片請求中引用它
Failed	擷取處理失敗	檢查格式與容量要求，然後重新新增

取得單一資產

此端點用於輪詢，每 5–10 秒一次，並設定整體逾時。處理通常需要數秒到數十秒；影片資產與尖峰時段會更久。

curl https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "status": "Active",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "url": "https://..."
}

url 是臨時的簽章下載位址。請勿儲存它；生成時請使用 asset_uri。

資產不存在或已被刪除時，上游服務會回傳 404，例如：

{ "details": "record not found", "error": "asset not found in database" }

列出與刪除資產

# List — asset_group_id is required
curl "https://api.routeapi.ai/v1/assets?asset_group_id=local_group_2c8186e6d8b44ffa73b371677bfe4af2" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

# Delete
curl -X DELETE https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

刪除資產會導致所有引用它的新影片請求失敗。

重新命名資產

curl -X PUT https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_asset_name"}'

{ "updated": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

重新命名後，資產詳情與列表中的名稱會回傳新值。

真人核驗工作階段

包含真人臉部的參考素材，必須先取得本人同意。核驗工作階段會為該人的素材建立專用資產組；新增到其中的資產會進行臉部一致性檢查。

建立工作階段

POST /v1/assets/verify-sessions

請求主體可以為空（{} 或完全不帶主體）。callback_url 會被接受，但不會用於重新導向。

curl https://api.routeapi.ai/v1/assets/verify-sessions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_id": "asset_sess_5e7860e76613dd51a4867bdcbea6076b",
  "status": "pending",
  "h5_link": "https://...one-time-link...",
  "callback_url": ""
}

h5_link 只能傳送給即將接受核驗的本人。它包含一次性憑證，可存取核驗頁面；請勿把它放進公開日誌、截圖或群組聊天。

取得工作階段

curl https://api.routeapi.ai/v1/assets/verify-sessions/asset_sess_5e7860e76613dd51a4867bdcbea6076b \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

status	含義
pending	等待本人操作，或仍在處理中
succeeded	核驗成功；asset_group_id 已填入
failed	核驗失敗；請讀取 error

{
  "session_id": "asset_sess_a8af6fab34f694ada40c22521448f579",
  "status": "succeeded",
  "result_code": "",
  "error": "",
  "asset_group_id": "group-20261015202316-4t5jt",
  "project_name": "default",
  "created_at": 1792066965,
  "updated_at": 1792067203
}

不會有 webhook 或重新導向回到你的服務——本人的瀏覽器最後會停在上游提供的結果頁。請輪詢工作階段直到 status 變成 succeeded（通常在幾分鐘內），然後把該人的素材新增到回傳的 asset_group_id。result_code 目前一律為空；請改用 status。若工作階段 status 為 failed 且 error 形如 verification expired，必須重新建立。

在 Seedance 請求中使用資產

在影片生成請求的 metadata.content 中引用資產，使用資產 API 回傳的 asset_uri：

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "The product in image 1 rotates slowly",
    "metadata": {
      "content": [
        { "type": "text", "text": "The product in image 1 rotates slowly" },
        {
          "type": "image_url",
          "image_url": { "url": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0" },
          "role": "reference_image"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "1:1"
    }
  }'

請從 GET /v1/models 中挑選支援影片生成的 Seedance 模型 ID；參見 Models。Seedance 的請求格式，包括 metadata.content 的 role 用法與各模型限制，記錄在Seedance中。

以下規則來自資產服務的契約：

• type/role 組合必須與資產類型相符：image_url 搭配 reference_image，video_url 搭配 reference_video，audio_url 搭配 reference_audio。
• 只有 Active 狀態的資產才能被引用。
• 提示詞以序號引用素材（“image 1”、“video 1”），序號依 content 順序在各類型內部計數。請勿在提示詞中寫入資產 ID。
• 真人素材必須來自已核驗的資產組；否則上游可能會拒絕請求或使任務失敗。

RouteAPI 會尋找任何以 asset:// 開頭的 JSON 字串值來判斷是否為引用（不區分大小寫）。這類請求會被固定到你的資產渠道並只送出一次，不重試，也不進行渠道故障轉移。以下情況下，請求會在本機被拒絕：

狀態	錯誤碼	原因
400	asset_key_required	請求主體引用了 asset://，但該帳戶尚無資產空間。請先建立資產組與資產
400	asset_remix_conflict	對非資產任務做 remix 時試圖引用 asset:// 資產
400	asset_channel_conflict	該 API Key 被固定到某個特定渠道，而該渠道不是你的資產渠道
400	asset_model_unsupported	你的資產渠道不支援該模型
503	asset_key_unavailable	綁定到該帳戶的上游憑證處於故障或被停用狀態

這些錯誤使用任務錯誤結構 {"code": ..., "message": ..., "data": ...}。

限制與錯誤

• 請求主體 — POST 與 PUT 主體以 1 MiB 上限讀取。超過上限時會在送往上游之前回傳 413。素材本身從不透過請求主體上傳；請傳入 URL。
• 主體格式 — 非空的 POST 或 PUT 主體必須是 JSON 物件。陣列、裸字串、null 以及無效 JSON 都會回傳 400，且不會到達上游服務。GET 與 DELETE 的主體會被忽略。
• 重新命名請求主體 — PUT 主體必須帶非空字串欄位 name（欄位名小寫）。缺少該欄位、值為空或不是字串時回傳 400，且不會到達上游服務。
• 回應主體 — 上游回應超過 10 MiB，或讀取失敗的回應，會回傳 502。
• 逾時 — 上游呼叫有固定的 60 秒逾時；逾時會以 502 回報。
• project_name — 若出現在 POST 或 PUT 主體中，該欄位會在轉發前被移除，不論字母大小寫。
• 擁有權錯誤 — 如果上游以 403 回傳擁有權拒絕（“you do not own” / “access denied”），RouteAPI 會改為回傳 404 {"error": "not found"}，讓該資源看起來不存在，而不是無權限。
• 上游憑證故障 — 上游 401 會變成 503 asset_key_unavailable，並把帳戶綁定標記為故障（見上文）。上游 402，或回應主體看起來像計費問題的上游錯誤，會變成 503 asset_service_unavailable。

其他上游狀態碼與主體會原樣透傳，包括上游的參數驗證錯誤。RouteAPI 自身的錯誤使用以下三種結構之一：

{ "error": "not found" }

{ "error": "<message>", "code": "asset_pool_busy" }

{
  "error": {
    "message": "token.invalid (request id: ...)",
    "type": "error",
    "code": ""
  }
}

第三種結構來自共用的認證與限流中介層，因此請先判斷 error 是字串還是物件。本機 message 文案目前為中文——對於前兩種結構，請依 HTTP 狀態碼與 code 欄位分支處理，而不要依賴 message。

狀態	錯誤碼	含義	處理
400	—	主體不是 JSON 物件，或上游拒絕了參數	修正請求；不要原樣重試
401	—	API Key 缺少、無效或已刪除	檢查 Authorization
404	—	未知的資產、資產組或工作階段；或該帳戶尚無資產空間	檢查 ID；若為新帳戶請先建立資產組
413	—	請求主體超過 1 MiB	改為傳入 URL，而不是內嵌資料
429	—	觸發限流	放慢輪詢頻率並稍後重試
500	asset_pool_internal_error	RouteAPI 無法讀寫自身的資產狀態	稍後重試
500	—	RouteAPI 在讀取帳戶資產狀態時失敗	稍後重試
502	—	上游無法連線、逾時，或回傳了無法讀取／過大的回應	稍後重試
503	asset_key_unavailable	帳戶的上游憑證處於故障或被停用狀態	聯絡客服；重試不會有幫助
503	asset_pool_exhausted	所屬分組沒有資產渠道，或沒有可分配的憑證	稍後重試或聯絡客服
503	asset_pool_busy	憑證存在，但目前無法分配任何一個	稍後重試
503	asset_pool_misconfigured	所屬分組對應到多個資產渠道	聯絡客服
503	asset_channel_unavailable	資產渠道本身被停用或設定錯誤	稍後重試或聯絡客服
503	asset_service_unavailable	上游帳戶餘額不足或發生重大故障	稍後重試或聯絡客服

資產呼叫不產生模型費用，但當平台啟用模型請求頻率限制時，它們會像其他任何 /v1 請求一樣計入限制。一般錯誤模型參見錯誤與除錯，消耗這些資產的影片生成如何計費，參見模型定價。

接下來

• 建立影片生成任務 — 所有影片模型共用的通用請求格式。
• Seedance — Seedance 請求格式與 metadata.content 的 role 用法。
• Models — 尋找支援的影片模型 ID。
• 錯誤與除錯 — 狀態碼與排查順序。