跳轉到主要內容

​
任務生命週期

提交 → 排隊(queued) → 處理中(processing) → 完成(completed) / 失敗(failed)
                ↓
          可取消(cancelled)，退還配額

​
任務狀態

狀態說明
queued任務已提交，等待處理
processing正在生成中，可查看進度
completed生成成功，結果可用
failed生成失敗，查看 error 資訊
cancelled使用者取消，配額已退還

​
提交任務

import openai

client = openai.OpenAI(
    base_url="https://qingbo.dev/v1",
    api_key="your-api-key"
)

# 提交非同步任務
response = client.post("/tasks", body={
    "model": "veo3",
    "action": "generate",
    "prompt": "A cat walking on the beach",
    "duration": 5
})

task_id = response["task_id"]
print(f"任務已提交: {task_id}")

​
輪詢狀態

import time

def wait_for_task(client, task_id, timeout=300):
    start = time.time()
    while time.time() - start < timeout:
        result = client.get(f"/tasks/{task_id}")
        status = result["status"]

        if status == "completed":
            return result["result"]
        elif status == "failed":
            raise Exception(f"任務失敗: {result['error']['message']}")

        time.sleep(2)  # 每 2 秒輪詢一次
    raise TimeoutError("任務逾時")

​
同步等待模式

如果不想手動輪詢，可以使用 /v1/tasks/sync：
  • 任務在逾時時間內完成 → 直接回傳結果
  • 逾時未完成 → 回傳 poll_url，繼續輪詢

​
Webhook 回呼

提交任務時設定 callback_url，任務完成後 WaveAPI 會主動推送結果： 
{
  "model": "veo3",
  "action": "generate",
  "prompt": "...",
  "callback_url": "https://your-server.com/webhook/task-done"
}

​
取消任務

只有 queued 狀態的任務可以取消，取消後配額自動退還： 
curl -X POST https://qingbo.dev/v1/tasks/{task_id}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
生成結果中的圖片/影片 URL 有有效期，請及時下載儲存。