非同步任務 - 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/* 中 object=image 或 object=video 的媒體任務。用戶端需要同時處理 HTTP 非 2xx 回應和 HTTP 200、status=failed 的任務終態。

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

提交 HTTP 5xx 錯誤回饋

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

HTTP 非 2xx 錯誤

invalid_request 和 schema_violation 列顯示的是後備 message 範本。服務能夠定位具體欄位或參數限制時會回傳動態 message；用戶端應以 code 判斷錯誤類型，不要依賴 message 固定比對。

HTTP	`code`	`message`	說明
400	`invalid_request`	`Invalid request. Check the request body and parameters.`（後備範本；實際可能回傳動態 message）	公共請求本文、欄位類型或清單參數不正確；此 code 的 message 不是固定值，能夠定位欄位時會回傳更具體的動態 message
400	`model_not_found`	`The requested model is not available. Check the model name and your account access.`	模型不存在、無法使用，或目前帳戶無權存取
400	`schema_violation`	`Invalid request: one or more parameters are invalid.`（後備範本；實際可能回傳動態 message）	請求不符合目前模型的參數 Schema；此 code 的 message 不是固定值，能夠定位欄位或限制時會回傳欄位層級的動態 message
400	`capability_not_supported`	`The requested parameters are not supported for this model.`	目前模型不支援請求中的欄位、數量或參數上限
400	`media_form_unsupported`	動態媒體提示，請見下文	圖片、影片、參考圖片或首尾幀的格式、資料、URL 或大小無法處理
400	`result_id_required`	`This task has multiple results. Specify result_id.`	任務包含多個結果，下載時未指定 `result_id`
400	`upstream_rejected`	`Upstream service rejected the request.`	模型推理廠商拒絕建立請求
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	API Key 缺少或無效
402	`insufficient_quota`	`Insufficient quota.`	AIHubMix 帳戶可用額度不足
403	`permission_denied`	`You do not have permission to access this resource.`	目前帳戶、API Key 或存取來源無權使用該資源
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to <console-url>/async-tasks to activate.`	目前帳戶未開啟非同步任務功能；主控台位址會依請求站點產生
404	`task_not_found`	`Task not found.`	任務不存在、分頁游標無效，或目前帳戶無權查看
404	`result_not_found`	`Result not found.`	結果不存在、尚未就緒、結果 ID 不相符，或目前帳戶無權下載
410	`artifact_expired`	`The result has expired.`	結果已超過保留期限
413	`request_too_large`	`Request body is too large. Reduce the request size and try again.`	整體請求本文超過 32 MiB
413	`image_too_large`	`Image is too large. Reduce the image size and try again.`	圖片介面解碼後的單張圖片超過模型處理上限
422	`image_not_generated`	`The expected image was not generated.`	模型推理廠商已完成請求，但未回傳可交付的圖片
429	`rate_limited`	`Too many requests. Please slow down and retry.`	AIHubMix 對目前帳戶或 API Key 限流
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	模型推理廠商回傳限流錯誤
429	`too_many_downloads`	`Download limit exceeded for this result.`	單一結果達到下載次數上限
500	`internal_error`	`Internal error. Please retry.`	服務發生呼叫方無法修復的內部錯誤
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	無法連線模型推理廠商，或無法完整讀取其回應
502	`upstream_bad_response`	`Upstream service returned an invalid response.`	模型推理廠商回傳平台無法處理的回應
502	`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	模型推理廠商回傳服務錯誤
503	`model_unavailable`	`The requested model is temporarily unavailable.`	所選模型暫時無法使用
503	`service_unavailable`	`Service is temporarily unavailable. Please retry.`	查詢、下載或結果服務暫時無法使用
504	`sync_timeout`	`Generation timed out. Please retry.`	同步生成未在等待時間內完成

media_form_unsupported 的 message 會依已確認的原因產生，常見範本如下：

情境	`message`
格式不支援	`Unsupported <media-kind> format: <detected-format>. Supported formats for this model: <allowed-formats>.`
圖片或影片資料無效	`The <media-kind> data is invalid. Provide a valid <media-kind>.`
無法確定媒體類型時的資料無效	`The media data is invalid. Provide valid media data.`
無法存取媒體 URL	`The <media-kind> URL could not be accessed. Make sure it is publicly accessible and returns a valid <media-kind>.`
無法解碼媒體	`Unable to process the <media-kind>. Check that the <media-kind> data or URL is valid and supported.`
非圖片任務的媒體超過限制	`The <media-kind> is too large. Reduce the <media-kind> size and try again.`
無法安全確定具體原因	`Unable to process the media. Check that the media data or URL is valid and supported.`

例如，模型允許 PNG、JPEG、WebP、HEIC 和 HEIF 時，GIF 圖片會回傳：

Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF.

HTTP 200 + Task `status=failed`

查詢請求成功不代表生成成功。任務為 failed 時，用戶端從任務物件的 error.code 和 error.message 讀取失敗原因：

{
  "id": "task_01K0ABCDEF",
  "status": "failed",
  "error": {
    "code": "media_form_unsupported",
    "message": "Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF."
  }
}

Task `code`	`message`	說明
`media_form_unsupported`	動態媒體提示，同上	非同步任務中的媒體格式、資料、URL、解碼或大小錯誤
`image_too_large`	`Image is too large. Reduce the image size and try again.`	非同步圖片任務的輸入圖片超過限制
`image_not_generated`	`The expected image was not generated.`	模型推理廠商未回傳可交付的圖片
`upstream_rejected`	`Upstream service rejected the request.`	模型推理廠商拒絕建立請求
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	模型推理廠商回傳限流錯誤
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	建立任務時無法連線模型推理廠商，或無法完整讀取其回應
`upstream_bad_response`	`Upstream service returned an invalid response.`	模型推理廠商的回應無法處理
`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	模型推理廠商建立或執行任務失敗
`upstream_empty_output`	`The upstream service completed without producing a usable result. Please retry.`	模型推理廠商已完成任務，但未產生可交付的結果
`output_policy_violation`	`Generated content was rejected by the content policy.`	生成內容未通過內容安全政策
`sync_timeout`	`Generation timed out. Please retry.`	等待生成結果逾時
`internal_error`	`Internal error. Please retry.`	非同步任務處理發生內部錯誤

完整影片範例

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 非 2xx 錯誤

​HTTP 200 + Task status=failed

​完整影片範例

​常見問題

快速開始

如何選擇三組介面

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

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

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

取得單一模型的請求 Schema

支援的模型和欄位

LLM 中斷恢復模型

如何建立圖片任務

同步圖片

非同步圖片

圖片標準欄位

如何建立影片任務

影片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載圖片

下載影片

如何使用 Webhook

回呼請求

重試與去重

LLM 中斷恢復如何生效

錯誤回應與錯誤碼

HTTP 非 2xx 錯誤

HTTP 200 + Task `status=failed`

完整影片範例

常見問題