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.

​
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