圖片生成

快速開始

原生圖片端點預設同步。將布林值 async 設為 true 可建立背景任務；以下使用 qwen-image-2.0。

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",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

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

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

如何探索非同步媒體模型並取得 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。

如何建立圖片任務

同步圖片

省略 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	否	特定模型的擴充參數

媒體任務物件

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

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "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/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

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

查詢媒體清單

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

curl "https://aihubmix.com/ai/v1/images?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": "image",
      "model": "qwen-image-2.0",
      "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=image&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": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

單一產物直接請求 /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 解碼。

如何使用 Webhook

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

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 tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "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": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

欄位	說明
`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 訂閱，並保留任務詳情查詢作為結果確認方式。

錯誤回應與錯誤碼

本節適用於 /ai/v1/images/* 和圖片任務。影片錯誤請見影片介面。

目前請求失敗：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	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	整個 HTTP 請求本文超過 32 MiB。請縮小實際傳送的請求本文，包括文字、參數和內嵌媒體編碼。

大小限制

媒體大小：圖片任務超限回傳 image_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.`	任務不存在，或不屬於目前帳戶。請檢查任務 ID，並確認 API Key 屬於建立任務的帳戶。
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": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

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.`	模型推理廠商已完成請求，但沒有回傳可用圖片。請調整請求或選擇其他模型後提交新任務；不要無條件自動重複生成。
`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。圖片、影片列表保留已取得的 expires_at。統一 /ai/v1/tasks 列表的讀取失敗資料列可能回傳 expires_at=null，結果仍受原保留期限制。上述處理僅適用於單筆結果無法讀取且沒有可用替代結果的情況。統一 tasks 介面整批查詢失敗仍回傳 HTTP 錯誤，詳情讀取的同類故障仍回傳 HTTP 500。相關文件：圖片介面 · 影片介面 · 非同步任務

完整範例

以下範例會建立非同步任務、輪詢並儲存所有回傳圖片。

import base64
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/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    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/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

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/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
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/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

開始使用

閘道能力

模型能力

協定參考

平台管理

快速開始

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

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

取得單一模型的請求 Schema

如何建立圖片任務

同步圖片

非同步圖片

圖片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載圖片

如何使用 Webhook

回呼請求

重試與去重

錯誤回應與錯誤碼

提交 HTTP 5xx 錯誤回報

HTTP 請求失敗

請求參數與媒體輸入

生成請求與回傳結果

帳戶與權限

服務可用性與速率限制

任務查詢與結果下載

任務執行失敗

列表單筆結果讀取失敗

完整範例

​快速開始

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

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

​取得單一模型的請求 Schema

​如何建立圖片任務

​同步圖片

​非同步圖片

​圖片標準欄位

​媒體任務物件

​狀態說明

​如何查詢媒體任務

​查詢媒體詳情

​查詢媒體清單

​如何使用統一任務介面

​如何下載媒體結果

​下載圖片

​如何使用 Webhook

​回呼請求

​重試與去重

​錯誤回應與錯誤碼

提交 HTTP 5xx 錯誤回報

​HTTP 請求失敗

​請求參數與媒體輸入

​生成請求與回傳結果

​帳戶與權限

​服務可用性與速率限制

​任務查詢與結果下載

​任務執行失敗

​列表單筆結果讀取失敗

​完整範例

快速開始

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

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

取得單一模型的請求 Schema

如何建立圖片任務

同步圖片

非同步圖片

圖片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載圖片

如何使用 Webhook

回呼請求

重試與去重

錯誤回應與錯誤碼

HTTP 請求失敗

請求參數與媒體輸入

生成請求與回傳結果

帳戶與權限

服務可用性與速率限制

任務查詢與結果下載

任務執行失敗

列表單筆結果讀取失敗

完整範例