Request & Response Format

Request Format

All requests use JSON and require these headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Successful Responses

Response shapes vary by endpoint, each following its own API spec:

Chat Completions — OpenAI standard response format
Claude Messages — Anthropic standard response format
Gemini — Google standard response format
Asynchronous Tasks — QWave API unified task response format

Billing Field (usage.cost)

Text and embedding endpoints return the actual charge of each call (quota, integer) in the usage object:

{
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "cost": 150
  }
}

Non-streaming → usage.cost in the response body
Streaming (SSE) → the last data frame carrying usage (see Streaming)
Async tasks → pre_consumed_cost on submission (pre-deduction), cost in the terminal state (settlement; 0 after refund on failure/cancellation)

For per-call reconciliation, the accumulated value of these fields matches your account balance deductions exactly.

Error Responses

Error structures differ slightly across endpoints: Synchronous endpoints (chat / messages / images, etc.) — OpenAI-compatible format with a type field:

{
  "error": {
    "message": "Detailed error description",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

Asynchronous task endpoints (/v1/tasks/...) — Simplified format with only message + code:

{
  "error": {
    "message": "Detailed error description",
    "code": "task_failed"
  }
}

Status Codes

Code	Meaning	How to Handle
400	Invalid request parameters	Check the request payload
401	Authentication failed	Verify your API key
402	Insufficient balance	Top up your account
404	Task or resource not found	Verify the task_id and that it belongs to your account
429	Rate limit exceeded / sliding-window quota exhausted (`code: quota_window_exceeded`, response includes `window`/`used`/`cap`/`reset_at`)	Reduce frequency or retry after `reset_at`
500	Internal server error	Retry later

Getting Started

Core Concepts

Request & Response Format

Request Format

Successful Responses

Billing Field (usage.cost)

Error Responses

Status Codes

​Request Format

​Successful Responses

​Billing Field (usage.cost)

​Error Responses

​Status Codes

Request Format

Successful Responses

Billing Field (usage.cost)

Error Responses

Status Codes