什麼是非同步生成
對於耗時的圖片生成請求,平台支援非同步生成模式:提交請求後立即返回任務 ID,客戶端透過輪詢獲取最終結果,不必保持長連線等待。
非同步模式適合生成時間較長的場景,能避免請求逾時中斷,也便於批次提交多個任務。
使用流程
非同步生成分為三步:提交任務 → 輪詢狀態 → 取得結果。
1. 提交任務
向 https://api.tvtapi.com/v1/images/async 發送 POST 請求,攜帶 API Key(Bearer 認證)和請求參數:
curl -X POST https://api.tvtapi.com/v1/images/async \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"模型名稱","prompt":"描述文本"}'
返回值中包含 task_id,這是後續查詢和下載的唯一憑證。
2. 輪詢任務狀態
用 task_id 輪詢任務狀態:
curl https://api.tvtapi.com/v1/images/async/{task_id} \
-H "Authorization: Bearer sk-xxxxxxxx"
任務狀態包括:queued(排隊中)、in_progress(生成中)、succeeded(成功)、failed(失敗)。建議每隔數秒輪詢一次,直到狀態變為 succeeded 或 failed。
3. 下載圖片
任務成功後,透過以下地址取得圖片:
curl -L https://api.tvtapi.com/v1/images/async/{task_id}/content \
-H "Authorization: Bearer sk-xxxxxxxx"
該端點會返回 302 重導向到圖片的實際儲存地址。每張圖片有下載次數限制,逾時後任務會自動過期。
也可在網頁端使用
如果不想寫程式碼,可以直接在 /zh-tw/user/image-studio 中使用圖片工作台。工作台內建非同步模式開關,切換後在頁面內自動輪詢並展示結果,無需手動呼叫 API。
注意事項
- 非同步功能需要管理員在後台開啟,且使用者帳戶需啟用對應權限
- 任務有效期間,過期後無法下載
- 如長時間停留在
in_progress,系統會自動逾時標記為failed