Skip to main content
影片生成、批次圖片生成這類請求的耗時通常超過一次 HTTP 連線的合理等待時間;長文字生成過程中用戶端一旦斷線,已經產生的回應也無法再取回。 非同步任務(Async Tasks)把這三類場景統一到同一個任務物件上:圖片、影片透過生成介面建立任務並立即回傳 task_id,用戶端中斷的 LLM 請求由平台繼續完成並儲存最終回應。三者共用相同的任務狀態、查詢介面和結果下載流程。
請使用建立任務時的同一個 API Key 查詢任務和下載結果。任務按 API Key 隔離,即使兩個 Key 屬於同一帳戶,也不能互相讀取任務。

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

建立非同步圖片或影片前,請先為目前帳戶開啟非同步任務功能。主控台暫未顯示該入口時,請聯絡 AIHubMix 技術支援。
未開啟非同步任務功能時,媒體任務建立請求回傳 403 async_not_enabled。LLM 請求不會因此報錯,但用戶端中斷後無法找回最終回應。

1. 快速開始

圖片和影片非同步任務的完整流程分為三步:

2. 同步呼叫與非同步任務的對比

同步呼叫在一次 HTTP 回應內回傳結果,連線中斷後結果無法找回。非同步任務把結果儲存在平台側,task_id 可以在結果過期前用同一個 API Key 重新查詢和下載,適用於耗時較長的生成請求,以及需要在中斷後取回最終回應的長文字輸出。

3. 介面總覽

Base URL:https://aihubmix.com,認證方式為 Bearer Token:
/ai/v1/tasks 是唯讀的統一查詢入口,不提供 POST /ai/v1/tasks。圖片和影片分別透過對應的生成介面建立;滿足 LLM 中斷恢復條件的請求會在用戶端中斷後自動記錄為 llm 任務。

4. 支援的模型

非同步任務按任務類型劃分支援範圍,呼叫時無需增加額外參數。

4.1 非同步圖片

4.2 非同步影片

4.3 LLM 中斷恢復

支援範圍會持續擴展,本表隨之更新。

5. 如何建立非同步任務

5.1 非同步圖片

圖片介面預設同步回傳。將 async 設定為 true 後,介面會立即回傳任務物件,生成過程在背景繼續執行。
async 必須是布林值。未傳或設定為 false 時,圖片介面保持同步行為。

5.2 非同步影片

影片介面始終非同步。建立成功後會回傳 pendingin_progress 狀態,不支援透過 Prefer: wait 改為同步等待。

5.3 公用參數

範例中的 modelpromptnsecondssize 是常見模型參數,各模型支援的欄位與取值以對應模型的 API 文件為準,影片模型可參考影片生成文件。下表只說明所有非同步任務共用的參數。
圖片任務只有在 async: true 時才能使用 Webhook。省略 webhook_events_filter 時,平台會推送 completedfailedcancelled 三種最終狀態;傳入時必須與 webhook_url 一起使用,並且不能為空、不能重複。

6. LLM 中斷恢復如何生效

LLM 中斷恢復用於取回用戶端斷開連線後的最終回應。該能力沿用現有的 LLM 請求方式,串流行為和回應格式保持不變,無需呼叫額外的建立介面,也不會預先回傳 task_id

6.1 生效條件

以下條件必須同時滿足: 支援的介面:
呼叫時無需傳入額外欄位。支援範圍見 4.3 LLM 中斷恢復;表中未列出的模型,可在正式接入前使用一條低成本請求完成中斷恢復驗證,驗證請求仍會正常計費。任一條件不滿足時,請求仍會正常執行,用戶端中斷後不會產生 llm 任務。

6.2 中斷後的執行流程

正常完成且成功回傳給用戶端的 LLM 請求不會建立任務,也不會出現在任務列表中。中斷請求會在最終回應儲存完成後出現在列表中,因此處理期間可能暫時查詢不到。

6.3 定位對應的中斷請求

LLM 回應標頭會回傳 X-Aihubmix-Request-Id。用戶端收到回應標頭後應立即儲存該值;發生中斷後,可在 AIHubMix 主控台的非同步任務列表中使用該請求 ID 尋找對應任務。 公開任務 API 目前不支援按請求 ID 篩選。未儲存請求 ID 時,只能使用建立請求時的同一個 API Key,按模型和建立時間尋找:
同一個 API Key 並行發起多個相同模型請求時,僅憑模型和建立時間無法保證精確對應。需要可靠恢復時,請儲存 X-Aihubmix-Request-Id 並透過主控台尋找;未取得回應標頭時,應避免將列表中的最新任務直接認定為本次請求。
LLM 中斷恢復任務目前不發送 Webhook,請透過任務列表查詢結果。用戶端中斷不會停止平台繼續處理請求,該次呼叫仍按原 LLM 介面規則計費。

7. 任務物件與狀態

所有任務使用統一回應結構:
output 中的結果欄位:

7.1 狀態說明

建議每 15 秒查詢一次,直到狀態變為 completedfailedcancelled
failedcancelled 任務也可能包含已經產生的部分結果。判斷是否有結果時,除狀態外還應檢查 output 是否為空。

8. 如何查詢任務

8.1 查詢任務詳情

該介面回傳查詢時的最新任務資訊。查詢操作不會改變任務,任務狀態由平台自動更新。

8.2 查詢任務列表

建立回應遺失,或者需要批次檢視歷史任務時,可以透過列表介面找回 task_id
回應範例:
繼續請求下一頁:

9. 如何取得任務結果

9.1 單產物任務

output 只有一個檔案時,可以直接存取:
也可以直接使用 output[0].content_url。下載回應的 Content-Typeoutput[0].content_type 一致。

9.2 多產物任務

output 包含多個檔案時,必須指定對應的 result_id
多產物任務未指定 result_id 時,介面回傳 400 result_id_required

9.3 LLM 回應任務

滿足 LLM 中斷恢復條件並儲存回應後,任務的 objectllmoutput 項的 typeresponse。內容類型可能是:
  • application/json:一般 JSON 回應
  • text/event-stream:已儲存的 SSE 串流回應
截斷標記位於任務詳情的 output[0].truncated。值為 true 時,表示已儲存的回應因大小限制被截斷。GET /ai/v1/tasks/{task_id}/content 回傳原始 JSON 或 SSE 內容,內容外不再包裝 truncated 欄位,因此應先查詢任務詳情再讀取內容。
結果可能過期,並且可能存在下載次數限制。請在 expires_at 之前及時儲存。過期回傳 410 artifact_expired,超過下載次數限制回傳 429 too_many_downloads

10. 如何使用 Webhook

目前支援在建立非同步任務時提交任務級 Webhook。需要任務完成後由 AIHubMix 主動通知時,請在非同步圖片或影片請求體中傳入 webhook_url 和可選的 webhook_events_filter
回呼網址必須使用 HTTPS,且不能指向本機、私有網路或其他受限位址。

10.1 回呼請求

AIHubMix 會向回呼網址傳送 POST 請求:
results 中的 URL 仍需攜帶建立任務時的 API Key 才能存取。

10.2 重試與去重

平台會至少嘗試投遞一次回呼,因此同一個事件可能被重複傳送:
  • HTTP 2xx 表示接收成功。
  • HTTP 5xx、網路錯誤或逾時會觸發重試。
  • HTTP 3xx4xx 不會重試。
  • 最多投遞 6 次,重試間隔依次為 1、4、16、64、256 秒。
接收端應儲存 event_id。再次收到相同 event_id 時,跳過業務邏輯並直接回傳 2xx
目前任務級 Webhook 不提供可設定的獨立簽章憑證。收到通知後,應使用建立任務時的 API Key 請求 GET /ai/v1/tasks/{task_id},以查詢結果為準。

11. 錯誤回應與錯誤碼

錯誤回應使用統一結構:

12. 完整範例

建立影片任務、輪詢狀態、下載全部結果的完整流程:

常見問題

建議多久查詢一次任務狀態? 建議每 15 秒查詢一次,避免高頻輪詢。使用 Webhook 時也應保留低頻查詢作為備用。 建立回應遺失後如何找回任務? 使用建立任務時的同一個 API Key 請求 GET /ai/v1/tasks,可以按 objectmodelstatus 縮小範圍。 為什麼同一帳戶的另一個 API Key 查不到任務? 任務按 API Key 隔離。查詢、下載和列表請求都必須使用建立任務時的同一個 Key。 為什麼任務失敗了但 output 不是空陣列? 部分模型可能在整體失敗或取消前已經產生了可交付結果。只要 output 中存在 content_urlb64_json,就可以按對應方式取得。 Webhook 沒收到怎麼辦? 確認回呼網址能公開存取、使用 HTTPS,並在 10 秒內回傳 2xx。無論是否使用 Webhook,都可以透過 GET /ai/v1/tasks/{task_id} 查詢最終狀態。 LLM 中斷恢復需要修改現有程式碼嗎? 不需要。請求方式、串流行為和回應格式保持不變。建議儲存回應標頭 X-Aihubmix-Request-Id,以便中斷後在主控台精確定位對應任務。
更新時間:2026-07-28