Task System

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

Models without a configured price are rejected at submission (HTTP 500, 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.

Getting Started

Core Concepts

Task Lifecycle

Task States

Submit a Task

Poll for Status

In-Request Waiting (Prefer: wait)

Billing & Refunds

Webhook Callbacks

Cancel a Task

​Task Lifecycle

​Task States

​Submit a Task

​Poll for Status

​In-Request Waiting (Prefer: wait)

​Billing & Refunds

​Webhook Callbacks

​Cancel a Task

Task Lifecycle

Task States

Submit a Task

Poll for Status

In-Request Waiting (Prefer: wait)

Billing & Refunds

Webhook Callbacks

Cancel a Task