Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Task Lifecycle

submit → queued → processing → completed / failed
                ↓
          cancelled (quota refunded)

​
Task States

StateDescription
queuedTask submitted and waiting to be processed
processingGeneration in progress; progress is available
completedGeneration succeeded; results are ready
failedGeneration failed; check the error field
cancelledCancelled 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")

​
Synchronous Wait Mode

If you’d rather not poll manually, use /v1/tasks/sync:
  • Task completes within the timeout → result is returned directly
  • Timeout exceeded → returns a poll_url so you can continue polling

​
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.