Skip to main content

​
Overview

QWave API endpoints fall into two categories:

Synchronous Endpoints

The request blocks until the result is ready. Best for fast operations like text generation and speech synthesis.

Asynchronous Tasks

The request returns a task_id immediately. Retrieve results via polling or webhook. Best for long-running jobs like image and video generation.

​
Synchronous Endpoints

These endpoints return results directly once processing completes:

​
Asynchronous Task Endpoints

Image and video generation use a unified asynchronous task system:
The task family is async-only. For “submit and wait” semantics, use POST /v1/tasks with a Prefer: wait=N header (N ≤ 60 seconds): if the task finishes within the window the full result is returned directly; otherwise the current state is returned and you continue polling. See Submit Task.

​
Async Task Webhook

If you would rather not poll, pass callback_url when submitting the task. When the task reaches a terminal state (completed / failed / cancelled) we POST to that URL once, with the same body GET /v1/tasks/{task_id} would return. Use callback_events to subscribe to only some terminal states; omit it and all three are delivered.
Delivery is best-effort — a network hiccup or a moment of downtime on your side can drop it. For anything critical, treat the callback as the fast path and keep a low-frequency poll as the safety net.

​
Choosing the Right Pattern

  • Text chat → Use synchronous endpoints with SSE streaming
  • Image generation → /v1/images/generations for simple cases, /v1/tasks for advanced workflows
  • Video generation → Use /v1/tasks (operations are long-running)
  • Need callback notifications → Use /v1/tasks with callback_url