task_id,用戶端中斷的 LLM 請求由平台繼續完成並儲存最終回應。三者共用相同的任務狀態、查詢介面和結果下載流程。
請使用建立任務時的同一個 API Key 查詢任務和下載結果。任務按 API Key 隔離,即使兩個 Key 屬於同一帳戶,也不能互相讀取任務。
前往主控台開啟非同步任務
建立非同步圖片或影片前,請先為目前帳戶開啟非同步任務功能。主控台暫未顯示該入口時,請聯絡 AIHubMix 技術支援。
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 非同步影片
影片介面始終非同步。建立成功後會回傳pending 或 in_progress 狀態,不支援透過 Prefer: wait 改為同步等待。
5.3 公用參數
範例中的model、prompt、n、seconds 和 size 是常見模型參數,各模型支援的欄位與取值以對應模型的 API 文件為準,影片模型可參考影片生成文件。下表只說明所有非同步任務共用的參數。
圖片任務只有在
async: true 時才能使用 Webhook。省略 webhook_events_filter 時,平台會推送 completed、failed 和 cancelled 三種最終狀態;傳入時必須與 webhook_url 一起使用,並且不能為空、不能重複。6. LLM 中斷恢復如何生效
LLM 中斷恢復用於取回用戶端斷開連線後的最終回應。該能力沿用現有的 LLM 請求方式,串流行為和回應格式保持不變,無需呼叫額外的建立介面,也不會預先回傳task_id。
6.1 生效條件
以下條件必須同時滿足:
支援的介面:
呼叫時無需傳入額外欄位。支援範圍見 4.3 LLM 中斷恢復;表中未列出的模型,可在正式接入前使用一條低成本請求完成中斷恢復驗證,驗證請求仍會正常計費。任一條件不滿足時,請求仍會正常執行,用戶端中斷後不會產生
llm 任務。6.2 中斷後的執行流程
6.3 定位對應的中斷請求
LLM 回應標頭會回傳X-Aihubmix-Request-Id。用戶端收到回應標頭後應立即儲存該值;發生中斷後,可在 AIHubMix 主控台的非同步任務列表中使用該請求 ID 尋找對應任務。
公開任務 API 目前不支援按請求 ID 篩選。未儲存請求 ID 時,只能使用建立請求時的同一個 API Key,按模型和建立時間尋找:
7. 任務物件與狀態
所有任務使用統一回應結構:output 中的結果欄位:
7.1 狀態說明
建議每 15 秒查詢一次,直到狀態變為
completed、failed 或 cancelled。
failed 或 cancelled 任務也可能包含已經產生的部分結果。判斷是否有結果時,除狀態外還應檢查 output 是否為空。8. 如何查詢任務
8.1 查詢任務詳情
8.2 查詢任務列表
建立回應遺失,或者需要批次檢視歷史任務時,可以透過列表介面找回task_id:
回應範例:
繼續請求下一頁:
9. 如何取得任務結果
9.1 單產物任務
output 只有一個檔案時,可以直接存取:
output[0].content_url。下載回應的 Content-Type 與 output[0].content_type 一致。
9.2 多產物任務
output 包含多個檔案時,必須指定對應的 result_id:
result_id 時,介面回傳 400 result_id_required。
9.3 LLM 回應任務
滿足 LLM 中斷恢復條件並儲存回應後,任務的object 為 llm,output 項的 type 為 response。內容類型可能是:
application/json:一般 JSON 回應text/event-stream:已儲存的 SSE 串流回應
output[0].truncated。值為 true 時,表示已儲存的回應因大小限制被截斷。GET /ai/v1/tasks/{task_id}/content 回傳原始 JSON 或 SSE 內容,內容外不再包裝 truncated 欄位,因此應先查詢任務詳情再讀取內容。
10. 如何使用 Webhook
目前支援在建立非同步任務時提交任務級 Webhook。需要任務完成後由 AIHubMix 主動通知時,請在非同步圖片或影片請求體中傳入webhook_url 和可選的 webhook_events_filter:
10.1 回呼請求
AIHubMix 會向回呼網址傳送POST 請求:
results 中的 URL 仍需攜帶建立任務時的 API Key 才能存取。
10.2 重試與去重
平台會至少嘗試投遞一次回呼,因此同一個事件可能被重複傳送:- HTTP
2xx表示接收成功。 - HTTP
5xx、網路錯誤或逾時會觸發重試。 - HTTP
3xx和4xx不會重試。 - 最多投遞 6 次,重試間隔依次為 1、4、16、64、256 秒。
event_id。再次收到相同 event_id 時,跳過業務邏輯並直接回傳 2xx。
11. 錯誤回應與錯誤碼
錯誤回應使用統一結構:12. 完整範例
建立影片任務、輪詢狀態、下載全部結果的完整流程:常見問題
建議多久查詢一次任務狀態? 建議每 15 秒查詢一次,避免高頻輪詢。使用 Webhook 時也應保留低頻查詢作為備用。 建立回應遺失後如何找回任務? 使用建立任務時的同一個 API Key 請求GET /ai/v1/tasks,可以按 object、model 和 status 縮小範圍。
為什麼同一帳戶的另一個 API Key 查不到任務?
任務按 API Key 隔離。查詢、下載和列表請求都必須使用建立任務時的同一個 Key。
為什麼任務失敗了但 output 不是空陣列?
部分模型可能在整體失敗或取消前已經產生了可交付結果。只要 output 中存在 content_url 或 b64_json,就可以按對應方式取得。
Webhook 沒收到怎麼辦?
確認回呼網址能公開存取、使用 HTTPS,並在 10 秒內回傳 2xx。無論是否使用 Webhook,都可以透過 GET /ai/v1/tasks/{task_id} 查詢最終狀態。
LLM 中斷恢復需要修改現有程式碼嗎?
不需要。請求方式、串流行為和回應格式保持不變。建議儲存回應標頭 X-Aihubmix-Request-Id,以便中斷後在主控台精確定位對應任務。
更新時間:2026-07-28