非同步任務 - AIHubMix

AIHubMix 提供三組任務介面：圖片使用 /ai/v1/images，影片使用 /ai/v1/videos，統一任務記錄使用 /ai/v1/tasks。

圖片生成預設同步，傳入 async: true 後非同步執行。
影片生成固定非同步。
圖片和影片詳情介面用於取得媒體任務的最新狀態。
/ai/v1/tasks 提供圖片、影片和 LLM 任務的統一唯讀檢視。

豆包 Seedance 影片需要引用真人素材時，先依豆包真人素材使用指南完成本人確認和素材準備，再建立影片任務。

影片教學：非同步任務

講解非同步任務的整體機制，並以非同步生圖為例示範完整呼叫流程。

前往主控台開啟非同步任務

使用 /ai/v1 媒體任務介面前，請先為目前帳戶開啟非同步任務功能。

未開啟非同步任務功能時，圖片和影片任務建立請求回傳 403 async_not_enabled。

快速開始

以下範例使用 wan2.6-t2v 建立影片。該模型接受 duration 和 size；不同模型的有效欄位可能不同。

# 1. 建立影片任務，儲存回應中的 id
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
    "duration": 5,
    "size": "1280x720"
  }'

# 2. 每 15 秒查詢一次媒體詳情
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3. completed 後下載影片
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

如何選擇三組介面

場景	方法	路徑	行為
生成圖片	POST	`/ai/v1/images/generations`	預設同步，可透過 `async: true` 改為非同步
查詢圖片詳情	GET	`/ai/v1/images/{id}`	回傳圖片任務狀態；查詢活動任務時可能更新狀態
查詢圖片清單	GET	`/ai/v1/images`	回傳目前帳戶建立的圖片任務快照
下載指定圖片	GET	`/ai/v1/images/{id}/content/{result_id}`	下載多圖任務中的指定結果
建立影片	POST	`/ai/v1/videos`	固定非同步
查詢影片詳情	GET	`/ai/v1/videos/{id}`	回傳影片任務狀態；查詢活動任務時可能更新狀態
查詢影片清單	GET	`/ai/v1/videos`	回傳目前帳戶建立的影片任務快照
下載影片	GET	`/ai/v1/videos/{id}/content`	下載任務的主要影片結果
取得非同步媒體模型清單	GET	`/api/v1/models?type={type}&schema_checked=true`	回傳已提供請求 Schema 的文生圖或文生影片模型
取得模型請求 Schema	GET	`/call/schema/models/{model}/endpoints`	回傳文生圖或文生影片端點及其 JSON Schema
查詢統一任務清單	GET	`/ai/v1/tasks`	唯讀查詢圖片、影片和 LLM 任務
查詢統一任務詳情	GET	`/ai/v1/tasks/{id}`	回傳查詢時的唯讀任務快照
取得統一任務結果	GET	`/ai/v1/tasks/{id}/content`	下載單一產物或讀取 LLM 存檔
取得指定統一任務結果	GET	`/ai/v1/tasks/{id}/content/{result_id}`	下載多產物任務中的指定結果

Base URL 為 https://aihubmix.com，驗證方式為 Bearer Token：

Authorization: Bearer $AIHUBMIX_API_KEY

模型清單與模型 Schema 都是公開探索介面，不需要 Bearer Token。其他介面都需要驗證。

/ai/v1/tasks 不提供建立介面。圖片和影片必須透過對應的媒體生成介面建立；LLM 恢復任務由平台在用戶端中斷後自動儲存。

媒體介面和統一任務介面的差異

媒體詳情介面與統一任務介面回傳相同的任務頂層欄位，但 output 項目和查詢行為不同：

比較項目	媒體詳情 `/images/{id}`、`/videos/{id}`	統一任務詳情 `/tasks/{id}`
任務類型	圖片或影片	圖片、影片或 LLM
查詢行為	查詢活動任務時可能更新狀態	回傳查詢時的唯讀任務快照
媒體輸出欄位	`index`、`type`、`content_url`、`b64_json`	`index`、`result_id`、`type`、`content_type`、`content_url`
LLM 輸出欄位	不適用	`index`、`type=response`、`content_type`、`content_url`、`truncated`
存取範圍	目前帳戶建立的對應媒體任務	目前 Bearer Token 建立的任務

因此，輪詢媒體生成狀態時應使用圖片或影片詳情介面；需要統一篩選任務、讀取結果中繼資料或恢復 LLM 回應時使用 /ai/v1/tasks。

如何探索非同步媒體模型並取得 Schema

探索流程分為兩個步驟。先從公開模型目錄取得支援非同步介面的文生圖或文生影片模型，再使用模型的 model_id 取得對應端點的請求 Schema。

取得支援非同步介面的模型清單

模型目錄與 Playground 使用相同的資料來源。type=image_generation 回傳文生圖模型，type=video 回傳文生影片模型。加入 schema_checked=true 後，清單只包含已發布並核對請求 Schema 的模型。

# 文生圖模型
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# 文生影片模型
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

兩個請求使用同一個介面。type 篩選目前只接受一個值，因此需要分別請求兩種模型類型。回應格式為 {success, message, data}。data 中與非同步媒體整合相關的欄位如下。

欄位	說明
`data[].model_id`	用於生成請求和後續 Schema 查詢的模型 ID
`data[].model_name`	模型顯示名稱
`data[].types`	逗號分隔的模型類型，可能同時包含 `image_generation` 和 `llm`
`data[].input_modalities`	逗號分隔的輸入模態
`data[].schema_checked`	`true` 代表請求 Schema 已發布並完成核對

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

取得單一模型的請求 Schema

不同模型支援的欄位、列舉和數值範圍可能不同。提交圖片或影片請求前，可以透過同一個公開介面取得指定模型目前可用的端點和請求 JSON Schema。

# 文生圖模型
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# 文生影片模型
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

回應中的 modality 為 image 或 video。endpoints 陣列中的每一項描述一個可用的呼叫協定。

欄位	說明
`default_endpoint`	目前模型的預設端點識別碼
`endpoints[].endpoint`	端點識別碼
`endpoints[].method`	請求方法，例如 `POST`
`endpoints[].path`	實際提交路徑
`endpoints[].content_types`	端點接受的內容類型
`endpoints[].lifecycle`	同步或非同步模式、輪詢路徑和狀態值
`endpoints[].request.schema`	該模型在對應端點下的完整請求 JSON Schema，包括必填欄位和取值限制

同一個模型可能同時回傳 /ai/v1 與 OpenAI 相容 /v1 端點。OpenAI 相容介面可能暫不支援最新模型，請優先使用 /ai/v1 端點。非同步任務介面應依 path 選擇 /ai/v1/images/generations 或 /ai/v1/videos，再讀取該項目的 request.schema。不要依賴 endpoints 陣列位置。下面的命令可以直接擷取兩個非同步任務端點的請求 Schema。

# 文生圖
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# 文生影片
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

模型不存在或尚未提供可探索端點時，介面回傳 404 model_not_found。端點資料暫時無法使用時回傳 500 endpoints_unavailable。

支援的模型和欄位

圖片和影片協定都定義了跨模型標準欄位，但每個模型會依據實際能力縮小欄位、列舉和數值範圍。呼叫前應透過模型 Schema 介面取得對應模型目前的參數限制。例如：

wan2.6-t2v 支援 duration、size 和 seed，不接受 resolution、aspect_ratio、frame_images、input_references 或 generate_audio。
qwen-image-2.0 支援 n、size、seed、negative_prompt、image 和 images，不接受 aspect_ratio 或 mask。

標準欄位集合不代表所有模型支援全部欄位。傳入目前模型不支援的欄位會回傳參數錯誤。

LLM 中斷恢復模型

目前支援以下模型：

gpt-5.6-sol
gpt-5.5-pro
gpt-5.4-pro
gpt-5.2-pro
claude-fable-5
claude-opus-5

支援範圍可能調整，請以本頁清單為準。使用中斷恢復還需要目前帳戶已開啟非同步任務功能。任一條件不符合時，原 LLM 請求仍會正常執行，但用戶端斷線後不會儲存恢復任務。

如何建立圖片任務

同步圖片

省略 async 或設定為 false 時，介面會等待生成完成並回傳任務物件：

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

同步圖片任務也會儲存任務記錄。用戶端連線中斷或建立回應遺失時，可以透過 GET /ai/v1/images 尋找對應任務。

非同步圖片

將 async 設定為布林值 true 後，介面會立即回傳任務物件，生成在背景繼續：

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

使用 GET /ai/v1/images/{id} 查詢非同步圖片任務。完成後，直接請求每個 output 項目中的 content_url；該 URL 已包含對應圖片的 result_id。

圖片請求中的 async 必須是布林值。webhook_url 和 webhook_events_filter 僅能與 async: true 一起使用。

圖片標準欄位

欄位	類型	必填	說明
`model`	string	是	模型名稱
`prompt`	string	是	圖片描述，不可為空
`n`	integer/null	否	圖片數量，最小值 `1`，預設 `1`
`size`	string/null	否	`{width}x{height}`，例如 `1024x1024`
`aspect_ratio`	string/null	否	長寬比；與 `size` 二選一
`seed`	integer/null	否	隨機種子
`negative_prompt`	string/null	否	負向提示詞
`image`	string/object	否	單張輸入圖片，可以是 URL、Data URI、Base64 或 `{url}` 物件
`images`	array/null	否	多張輸入圖片
`mask`	string/object	否	圖片編輯遮罩
`output_format`	string/null	否	`png`、`jpeg` 或 `webp`，預設 `png`
`response_format`	string/null	否	`url` 或 `b64_json`，預設 `url`
`async`	boolean	否	設為 `true` 時非同步執行
`webhook_url`	string	否	HTTPS 回呼位址，最長 512 個字元
`webhook_events_filter`	string[]	否	`completed`、`failed`、`cancelled` 的非空子集
`extra`	object/null	否	特定模型的擴充參數

如何建立影片任務

影片請求一律非同步，不支援透過 Prefer: wait 改為同步等待。標準協定使用整數 duration 表示秒數：

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'

影片標準欄位

欄位	類型	必填	說明
`model`	string	是	模型名稱
`prompt`	string	是	影片描述，不可為空
`duration`	integer/null	否	影片時長，單位為秒；具體範圍由模型決定
`aspect_ratio`	string/null	否	長寬比，協定預設值為 `16:9`
`resolution`	string/null	否	`480p`、`720p`、`1080p`、`1K`、`2K` 或 `4K`
`size`	string/null	否	`{width}x{height}`；可取代 `resolution` 與 `aspect_ratio`
`seed`	integer/null	否	隨機種子
`input_references`	array/null	否	圖片、影片或音訊參考素材
`frame_images`	array/null	否	首幀或尾幀圖片
`generate_audio`	boolean/null	否	是否生成音軌
`webhook_url`	string	否	HTTPS 回呼位址，最長 512 個字元
`webhook_events_filter`	string[]	否	`completed`、`failed`、`cancelled` 的非空子集
`extra`	object/null	否	特定模型的擴充參數

input_references 項目的結構：

{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}

type 可以是 image_url、video_url 或 audio_url。 frame_images 項目的結構：

{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}

frame_type 可以是 first_frame 或 last_frame。

媒體任務物件

圖片和影片專用介面回傳以下結構：

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}

欄位	類型	說明
`id`	string	平台任務 ID
`object`	string	`image` 或 `video`
`model`	string	模型名稱
`status`	string	目前任務狀態
`output`	array	已生成的結果；尚無結果時為空陣列
`error`	object/null	失敗資訊，可包含 `code`、`message` 和 `upstream_detail`
`created_at`	integer	建立時間，Unix 秒
`completed_at`	integer/null	最終狀態時間，Unix 秒
`expires_at`	null	媒體專用介面目前回傳 `null`

媒體 output 項目：

欄位	類型	說明
`index`	integer	結果順序，從 `0` 開始
`type`	string	目前為 `file`
`content_url`	string/null	結果下載位址
`b64_json`	string/null	Base64 編碼的圖片結果

狀態說明

狀態	是否結束	說明
`pending`	否	平台已接收任務，等待執行
`in_progress`	否	任務正在執行
`completed`	是	任務完成，可讀取 `output`
`failed`	是	任務失敗，原因請見 `error`
`cancelled`	是	任務已取消

用戶端可以每 15 秒查詢一次，直到狀態變為 completed、failed 或 cancelled。15 秒是用戶端輪詢建議，不是伺服器協定限制。

如何查詢媒體任務

查詢媒體詳情

# 圖片
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 影片
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

媒體詳情介面可回傳更新後的任務狀態，因此媒體輪詢應使用對應的圖片或影片詳情介面。

查詢媒體清單

建立回應遺失時，可以透過對應媒體清單找回任務 ID：

curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

參數	類型	預設值	說明
`after`	string	-	分頁游標，使用上一頁的 `next_after`
`limit`	integer	`20`	每頁數量，最大 `100`
`order`	string	`desc`	傳入 `asc` 時升冪，其他值按 `desc` 處理

{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}

媒體清單回傳查詢時的任務快照，不會主動更新任務狀態。

如何使用統一任務介面

統一任務介面支援以下篩選條件：

curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

參數	類型	預設值	說明
`object`	string	-	`llm`、`image` 或 `video`
`status`	string	-	`pending`、`in_progress`、`completed`、`failed` 或 `cancelled`
`model`	string	-	按模型名稱精確篩選
`after`	string	-	分頁游標
`limit`	integer	`20`	範圍 `1` 到 `100`
`order`	string	`desc`	`asc` 或 `desc`

統一任務詳情：

curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

媒體任務的統一 output 項目：

{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}

單一產物直接請求 /ai/v1/tasks/{id}/content。多產物任務需要請求 /ai/v1/tasks/{id}/content/{result_id}；未指定結果 ID 時回傳 400 result_id_required。

統一任務清單、詳情和內容介面按建立任務時的 Bearer Token 隔離。同一帳戶下的其他 API Key 無法讀取該任務。

如何下載媒體結果

下載圖片

圖片完成後，逐項請求媒體任務物件中的 output[].content_url：

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

圖片的媒體下載路徑為 /ai/v1/images/{id}/content/{result_id}。媒體任務物件不另外公開 result_id，用戶端直接使用 content_url 即可。當 b64_json 非空時，可以直接對該欄位進行 Base64 解碼。

下載影片

curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

結果可能過期，並且可能存在下載次數限制。過期回傳 410 artifact_expired，超過下載次數限制回傳 429 too_many_downloads。

如何使用 Webhook

非同步圖片和影片支援任務層級 Webhook：

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil garden at sunrise",
    "duration": 5,
    "size": "1280x720",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'

webhook_url 最長 512 個字元，並且不能指向本機、私人網路或其他受限位址。省略 webhook_events_filter 時，平台推送 completed、failed 和 cancelled；明確傳入時，陣列不可為空、不可重複，並且必須與 webhook_url 一起使用。未在請求中傳入 webhook_url 時，非同步圖片和影片會嘗試使用帳戶中設定的預設回呼位址。無效的帳戶預設位址會被忽略，不會阻止任務建立。

回呼請求

{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}

欄位	說明
`event_id`	回呼事件 ID，用於去重
`event_type`	`completed`、`failed` 或 `cancelled`
`created_at`	RFC 3339 格式的事件時間
`data.task_id`	平台任務 ID
`data.status`	目前最終狀態
`data.model`	模型名稱
`data.results[].url`	完成時可能回傳的結果下載位址
`data.error`	失敗時可能回傳的錯誤資訊

results 僅在結果已存檔時出現，下載仍需要 Bearer Token。

重試與去重

平台採用至少一次投遞，同一個事件可能重複送達：

HTTP 2xx 表示接收成功。
HTTP 5xx、網路錯誤或逾時會觸發重試。
HTTP 3xx 和 4xx 不會重試。
最多投遞 6 次，重試間隔依序為 1、4、16、64、256 秒。

接收端應儲存 event_id，重複收到相同事件時直接回傳 2xx。

任務層級 Webhook 本身不含獨立簽章金鑰。需要簽章驗證時，請設定帳戶層級 Webhook 訂閱，並保留任務詳情查詢作為結果確認方式。

LLM 中斷恢復如何生效

LLM 中斷恢復用於取回用戶端斷線後的最終回應。請求方式、串流行為和回應格式保持不變，也不會在請求開始時預先回傳任務 ID。以下條件需要同時符合：

條件	說明
帳戶已開啟非同步任務功能	在 AIHubMix 主控台為目前帳戶開啟
模型支援中斷恢復	目前模型在 LLM 中斷恢復模型清單中
介面受支援	Chat Completions、Anthropic Messages、Responses API 或 Gemini `generateContent` / `streamGenerateContent`
用戶端中斷	用戶端取消、網路斷線或呼叫端取消請求

平台僅在偵測到回應未完整交付且用戶端已斷線時建立恢復任務，並儲存最終 JSON 或 SSE。正常完成並完整交付給用戶端的 LLM 請求不會建立恢復任務。 LLM 回應標頭包含 X-Aihubmix-Request-Id。用戶端應儘早儲存該值，以便在主控台中定位對應請求。公開任務 API 目前無法按請求 ID 篩選；可以按模型和建立時間查詢最近的 LLM 任務：

curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

LLM 任務的統一 output 項目包含 type=response、content_type、content_url 和 truncated。GET /ai/v1/tasks/{id}/content 回傳儲存的原始 JSON 或 SSE。

LLM 中斷恢復任務目前不傳送任務層級 Webhook。用戶端中斷不會停止平台繼續處理請求，該次呼叫仍按原介面規則計費。

錯誤回應與錯誤碼

本節適用於 /ai/v1/images/*、/ai/v1/videos/* 及已識別為圖片或影片的 /ai/v1/tasks/*。LLM 任務維持原有錯誤規範；未指定媒體類型且尚未取得 Task 的查詢繼續使用通用錯誤規範。

目前請求失敗：HTTP 非 2xx，表示本次建立、查詢或下載請求失敗，請見 HTTP 請求失敗。
任務執行失敗：查詢回傳 HTTP 200，但任務的 status=failed，原因記錄在任務內的 error，請見任務執行失敗。
列表單筆結果讀取失敗：列表回傳 HTTP 200，但某筆任務帶有 output_error，請見列表單筆結果讀取失敗。

下表 message 欄列出英文回傳訊息，說明欄解釋含義及處理方式。參數驗證錯誤列出通用訊息，實際回應可能進一步指出具體欄位和限制。用戶端應使用 code 判斷錯誤類型，不應依賴完整 message 比對。

{
  "error": {
    "message": "The task was not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

提交 HTTP 5xx 錯誤回報

請求回傳 HTTP 5xx 時，請提交回報並附上 error.tid。

HTTP 請求失敗

下表中的 HTTP 狀態用於目前請求直接失敗的情況。已建立任務的執行失敗請見下方「任務執行失敗」表。

請求參數與媒體輸入

HTTP	`code`	`message`	說明
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	請求本文、查詢參數或參數類型不正確。請依錯誤訊息檢查請求格式、參數類型和取值。
404	`model_not_found`	`The requested model was not found. Check the model name.`	請求的模型不存在。請檢查模型名稱。
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	參數不符合所選模型的輸入要求。請查閱該模型的 schema，修正錯誤訊息指出的欄位。
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	目前模型不支援該操作與媒體輸入組合。請更換輸入組合或選擇支援該組合的模型。
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	請求參數超出模型能力範圍。請依錯誤訊息調整參數，或選擇其他模型。
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	該模型不支援目前的媒體格式。請使用錯誤訊息或 `error.details.allowed_mime_types` 中列出的格式；未提供列表時，請查閱該模型的輸入要求。
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	已確認媒體資料無效，例如 base64 損壞或 data URI 結構錯誤。請檢查資料完整性和編碼，重新提供有效媒體。
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	媒體連結無法存取或讀取。請檢查連結是否有效、是否允許公開存取，以及是否回傳有效媒體內容。
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	媒體輸入無法處理，目前無法確認更具體的原因。請檢查媒體資料或連結是否有效，以及格式是否受模型支援。
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	圖片任務的媒體內容超過目前處理上限。請依 `error.details.max_bytes` 或錯誤訊息中的上限縮小媒體後再試。
413	`media_too_large`	`The {media_kind} exceeds the allowed size of {max_bytes} bytes. Reduce its size and try again.`	其他媒體任務的媒體內容超過目前處理上限。請依 `error.details.max_bytes` 或錯誤訊息中的上限縮小媒體後再試。
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	整個 HTTP 請求本文超過 32 MiB。請縮小實際傳送的請求本文，包括文字、參數和內嵌媒體編碼。

大小限制

媒體大小：圖片任務超限回傳 image_too_large，其他媒體任務回傳 media_too_large。影片任務上傳參考圖片時也使用 media_too_large。具體上限請見錯誤訊息或 error.details.max_bytes。
整個請求大小：request_too_large 表示 HTTP 請求本文超過 32 MiB，包括文字、參數和內嵌媒體編碼。只傳 URL 時，連結本身計入請求本文，連結指向的檔案仍須符合模型的媒體限制。
實際大小：error.details.actual_bytes 僅在完整大小已確認時提供。透過 URL 讀取媒體時，若達到讀取上限後停止，可能不回傳此欄位。

支援格式 以所選模型為準。請先查看 error.details.allowed_mime_types 或錯誤訊息中的格式列表；未提供列表時，請查閱該模型的 Schema。 訊息中的預留位置

{media_kind}：實際媒體類型。類型已確認時，invalid_media_data 和 media_url_unreachable 的訊息也會使用 image 或 video。
{max_bytes}：位元組上限。圖片上限未知時，回傳 The image is too large. Reduce the image size and try again.
{allowed_formats}：允許的格式列表。格式錯誤訊息可能追加 Use one of: {allowed_formats}.

生成請求與回傳結果

HTTP	`code`	`message`	說明
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	模型推理廠商已完成請求，但沒有回傳可用圖片。請調整請求或選擇其他模型後再試；持續失敗時，請提供請求 ID 聯絡支援。不要僅因 HTTP 502 就無條件自動重複生成。
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	模型推理廠商攔截了生成內容，且未回傳可用圖片。請修改提示詞或輸入內容後再試。本次不收取生成費用。
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	模型推理廠商拒絕了請求，但僅憑此碼不能確定是內容違規。請檢查請求參數和輸入內容，修改後再試。
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	模型推理廠商已回傳回應，但平台無法處理；不表示已確認沒有生成結果。請提供請求 ID 聯絡支援，不要自行判定為參數錯誤或空結果。
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	豆包回傳了特定的真人圖片隱私拒絕碼。請先完成真人認證，再使用已啟用的 `asset://` 素材；詳見真人素材文件。
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	生成未能在等待時間內完成；逾時不證明請求沒有執行。請提供請求 ID 聯絡支援；不要查詢未回傳給你的任務 ID。
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	任務已提交給模型推理廠商，後續狀態無法確認。請勿重複提交；請提供請求 ID 聯絡支援，有任務 ID 時一併提供。

帳戶與權限

HTTP	`code`	`message`	說明
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	API Key 缺失或無效。請檢查 `Authorization` 請求標頭和 API Key。
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	帳戶額度不足。請補充帳戶額度後再試。
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	帳戶或 API Key 無權存取。請檢查帳戶權限、API Key 權限和 IP 限制。
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	帳戶未開啟非同步任務功能。請依回應中的控制台連結開通後再試。

服務可用性與速率限制

HTTP	`code`	`message`	說明
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	請求過於頻繁。請降低請求頻率後再試。
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	模型推理廠商限制請求速率。請稍後再試，避免立即反覆提交。
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	平台發生內部錯誤。請提供請求 ID 聯絡支援，不需要反覆修改正常輸入。
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	模型推理廠商暫時不可用，可能是連線失敗、廠商服務錯誤或回應讀取失敗。僅憑此碼無法確認是否已產生結果；持續失敗時，請提供請求 ID 聯絡支援。
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	模型推理廠商不可用。表中為預設訊息，實際回應可能提供更具體的提示；錯誤類型以 `code` 為準。請提供請求 ID 聯絡支援。
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	目前模型暫時不可用。請稍後再試或選擇其他模型；持續失敗時，請提供請求 ID 聯絡支援。
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	目前服務暫時不可用。請稍後重試目前操作；下載失敗時重試下載，不必重新生成。

provider_unavailable 表示已明確識別的模型推理廠商故障。僅憑一般 429 或 4xx 無法確認帳戶額度、內容審核或參數問題。

任務查詢與結果下載

HTTP	`code`	`message`	說明
404	`task_not_found`	`The task was not found.`	任務不存在或無權查看。圖片、影片專屬介面依帳戶檢查歸屬；統一 `/ai/v1/tasks` 介面須使用建立任務時的 API Key。請檢查任務 ID 和所用憑證。
404	`result_not_found`	`The result was not found.`	結果不存在或無權讀取。請檢查任務 ID、結果 ID 和 API Key；已知無效的結果 ID 不會因為任務仍在執行而變成 409。
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	分頁游標無效或已失效。請移除 `after`，從第一頁重新查詢，再使用該列表回傳的新游標。
400	`result_id_required`	`This task has multiple results. Specify result_id.`	任務有多個結果，但未指定 `result_id`。請從任務輸出中選擇結果，並指定對應的 `result_id`。
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	任務仍在排隊或執行，結果尚未準備好。請繼續查詢任務狀態，結果就緒後再下載；不需要重新生成。
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	結果已超過保留期。已過期的結果無法繼續下載，需要時請提交新的生成請求。
429	`too_many_downloads`	`Download limit exceeded for this result.`	下載次數達到限制。請檢查已儲存的結果；單純等待不保證恢復下載次數。

任務執行失敗

任務建立成功後，生成失敗透過 status=failed 和任務內的 error 表達。查詢成功仍回傳 HTTP 200。

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "result_delivery_failed",
    "message": "The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID."
  }
}

Task `code`	`message`	說明
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	模型推理廠商已完成請求，但沒有回傳可用圖片。請調整請求或選擇其他模型後提交新任務；不要無條件自動重複生成。
`provider_empty_output`	`The model provider completed the task without a usable result. Adjust the request or choose another model, then submit a new task.`	已確認影片或其他媒體生成完成，但沒有可用結果。請調整請求或選擇其他模型後提交新任務。
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	模型推理廠商攔截了生成內容，且未回傳可用圖片。請修改提示詞或輸入內容後提交新任務。本次不收取生成費用。
`output_policy_violation`	`Generated content was rejected by the content policy.`	生成內容未通過審核。請修改提示詞或輸入內容後提交新任務；依現有內容審核收費規則處理，歷史費用以計費記錄為準。
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	模型推理廠商拒絕了請求，但僅憑此碼不能確定是內容違規。請檢查請求參數和輸入內容，修改後提交新任務。
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	平台無法處理模型推理廠商回傳的回應；不表示已確認沒有生成結果。請提供任務 ID 聯絡支援。
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	任務已提交給模型推理廠商，後續狀態無法確認。請勿重複提交；請提供任務 ID 聯絡支援。
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	已有生成結果，但平台未能完成儲存或交付。請勿自動重新生成；請提供任務 ID 聯絡支援，先排查已有結果。
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	模型推理廠商限制請求速率。請稍後再試，避免立即反覆提交。
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	任務執行期間遇到模型推理廠商連線失敗、廠商服務錯誤或回應讀取失敗。僅憑此碼無法確認是否已產生結果；持續失敗時，請提供任務 ID 聯絡支援。
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	模型推理廠商不可用。表中為預設訊息，實際回應可能提供更具體的提示；錯誤類型以 `code` 為準。請提供任務 ID 聯絡支援。
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	豆包回傳了特定的真人圖片隱私拒絕碼。請先完成真人認證，再使用已啟用的 `asset://` 素材；詳見真人素材文件。
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	生成任務逾時。請提供任務 ID 聯絡支援。
`internal_error`	`An internal error occurred. Contact support with the task ID.`	平台發生內部錯誤。請提供任務 ID 聯絡支援，不需要反覆修改正常輸入。

媒體輸入錯誤也可能出現在失敗 Task 中，錯誤碼含義與上方媒體輸入表一致；此時查詢成功的 HTTP 狀態仍為 200。媒體大小錯誤的 message 結尾使用 submit a new task.，提示縮小媒體後提交新任務。 output_blocked 表示明確攔截且未回傳可用圖片，本次不收取生成費用。output_policy_violation 依現有內容審核收費規則處理。歷史費用請以計費記錄為準。

列表單筆結果讀取失敗

圖片、影片任務列表中的個別資料列可能附帶 output_error：

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

此欄位表示本次無法讀取該筆結果。列表仍回傳 HTTP 200，該筆資料的 output=[]，原 id、status、error 和分頁保持不變，其他可正常讀取的任務不受影響。即使 status=completed，也應檢查 output_error，再判斷結果是否可讀取。請提供 output_error.tid 聯絡支援；該欄位未帶 tid 時，可提供本次回應標頭中的請求 ID。此錯誤不改變任務狀態或費用，也不觸發 Webhook。統一 /ai/v1/tasks 列表的讀取失敗資料列可能回傳 expires_at=null，結果仍受原保留期限制。圖片、影片專屬列表保留已取得的過期時間。上述處理僅適用於單筆結果無法讀取且沒有可用替代結果的情況。統一 tasks 介面整批查詢失敗仍回傳 HTTP 錯誤，詳情讀取的同類故障仍回傳 HTTP 500。相關文件：圖片介面 · 影片介面 · 非同步任務

完整影片範例

import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/videos",
    headers=headers,
    json={
        "model": "wan2.6-t2v",
        "prompt": "A cat playing jazz on a piano",
        "duration": 5,
        "size": "1280x720",
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] == "completed":
    result = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}/content",
        headers=headers,
        timeout=120,
    )
    result.raise_for_status()
    with open("result.mp4", "wb") as file:
        file.write(result.content)
else:
    raise RuntimeError(task.get("error") or task["status"])

import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "wan2.6-t2v",
    prompt: "A cat playing jazz on a piano",
    duration: 5,
    size: "1280x720",
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status === "completed") {
  const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, {
    headers,
  });
  if (!result.ok) throw new Error(await result.text());
  await writeFile("result.mp4", Buffer.from(await result.arrayBuffer()));
} else {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

常見問題

媒體任務應該查詢 /ai/v1/tasks/{id} 還是媒體詳情介面？ 輪詢生成狀態時使用媒體詳情介面：圖片查詢 /ai/v1/images/{id}，影片查詢 /ai/v1/videos/{id}。/ai/v1/tasks/{id} 回傳唯讀快照。 為什麼影片請求中的 seconds 回傳參數錯誤？ /ai/v1/videos 標準協定使用整數 duration，單位為秒。具體允許值由對應模型支援的參數決定。 為什麼 resolution 在部分影片模型中回傳參數錯誤？ 標準影片協定包含 resolution 和 size，但具體模型會縮小欄位。例如 wan2.6-t2v 使用 size，不接受 resolution。 建立回應遺失後如何找回媒體任務？ 圖片請求 GET /ai/v1/images，影片請求 GET /ai/v1/videos。清單支援 after、limit 和 order 分頁參數。 為什麼兩種詳情介面的 output 欄位不同？ 媒體詳情介面提供直接下載所需的簡化欄位；統一任務介面額外提供 result_id 和 content_type，並為 LLM 存檔提供 truncated。 Webhook 沒收到怎麼辦？ 確認回呼位址可公開存取並及時回傳 2xx，然後使用媒體詳情介面查詢最終狀態。

更新時間：2026-08-12

影片教學：非同步任務

前往主控台開啟非同步任務

​快速開始

​如何選擇三組介面

​媒體介面和統一任務介面的差異

​如何探索非同步媒體模型並取得 Schema

​取得支援非同步介面的模型清單

​取得單一模型的請求 Schema

​支援的模型和欄位

​LLM 中斷恢復模型

​如何建立圖片任務

​同步圖片

​非同步圖片

​圖片標準欄位

​如何建立影片任務

​影片標準欄位

​媒體任務物件

​狀態說明

​如何查詢媒體任務

​查詢媒體詳情

​查詢媒體清單

​如何使用統一任務介面

​如何下載媒體結果

​下載圖片

​下載影片

​如何使用 Webhook

​回呼請求

​重試與去重

​LLM 中斷恢復如何生效

​錯誤回應與錯誤碼

提交 HTTP 5xx 錯誤回報

​HTTP 請求失敗

​請求參數與媒體輸入

​生成請求與回傳結果

​帳戶與權限

​服務可用性與速率限制

​任務查詢與結果下載

​任務執行失敗

​列表單筆結果讀取失敗

​完整影片範例

​常見問題

快速開始

如何選擇三組介面

媒體介面和統一任務介面的差異

如何探索非同步媒體模型並取得 Schema

取得支援非同步介面的模型清單

取得單一模型的請求 Schema

支援的模型和欄位

LLM 中斷恢復模型

如何建立圖片任務

同步圖片

非同步圖片

圖片標準欄位

如何建立影片任務

影片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載圖片

下載影片

如何使用 Webhook

回呼請求

重試與去重

LLM 中斷恢復如何生效

錯誤回應與錯誤碼

HTTP 請求失敗

請求參數與媒體輸入

生成請求與回傳結果

帳戶與權限

服務可用性與速率限制

任務查詢與結果下載

任務執行失敗

列表單筆結果讀取失敗

完整影片範例

常見問題