Task Lifecycle
submit → queued → processing → completed / failed
↓
cancelled (quota refunded)
Task States
| State | Description |
|---|
queued | Task submitted and waiting to be processed |
processing | Generation in progress; progress is available |
completed | Generation succeeded; results are ready |
failed | Generation failed; check the error field |
cancelled | Cancelled by the user; quota has been refunded |
Submit a Task
import openai
client = openai.OpenAI(
base_url="https://www.qingbo.dev/v1",
api_key="your-api-key"
)
# Submit an asynchronous task
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 submitted: {task_id}")
Poll for Status
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"Task failed: {result['error']['message']}")
time.sleep(2) # Poll every 2 seconds
raise TimeoutError("Task timed out")
In-Request Waiting (Prefer: wait)
If you’d rather not poll manually, submit with a Prefer: wait=N header (N ≤ 60 seconds):
- Task completes within the window → the full terminal result is returned directly (including
result and cost)
- Window exceeded → the current state is returned; continue polling
GET /v1/tasks/{task_id}
Billing & Refunds
| Stage | Field | Meaning |
|---|
| Submitted | pre_consumed_cost | Quota pre-deducted from your balance |
completed | cost | Final settled charge — use for reconciliation |
failed / cancelled | cost: 0 | Pre-deducted quota is automatically refunded in full |
code: price_not_configured) — a task is never accepted and then mis-billed.
Webhook Callbacks
Set callback_url when submitting a task and QWave API will push the result to your endpoint when the task finishes:
{
"model": "veo3",
"action": "generate",
"prompt": "...",
"callback_url": "https://your-server.com/webhook/task-done"
}
Cancel a Task
Only queued tasks can be cancelled. Cancellation automatically refunds the quota:
curl -X POST https://www.qingbo.dev/v1/tasks/{task_id}/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Image and video URLs in task results have a limited lifetime — download and store them promptly.
