AIWave API: Complete Reference

This page is generated from the public OpenAPI 3.1 contract verified on September 13, 2026. The machine-readable source is /openapi.json. Route-dependent model capabilities still need a controlled request.

Base URL and authentication

https://aiwave.live/v1
Authorization: Bearer $AIWAVE_API_KEY
Content-Type: application/json

Create a key in the Console, store it in an environment variable, and never place it in browser code or a public repository. The pricing and status snapshots are public; model discovery and completions require a bearer key.

Minimal chat request

curl https://aiwave.live/v1/chat/completions \
  -H "Authorization: Bearer $AIWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Reply with exactly: route ok"}]}'

The response follows the OpenAI Chat Completions shape. Use the exact model ID returned by GET /v1/models. Set stream: true for Server-Sent Events and stop reading when the stream emits [DONE].

Endpoints

POST/v1/chat/completions

Create a chat completion

Send an OpenAI-shaped chat request. Route-dependent fields must be verified with the selected model.

Access: Bearer key Responses: 200 400 401 402 403 429 500

GET/v1/models

List model IDs visible to the current key

Access: Bearer key Responses: 200 401 402 429 500

GET/api/v1/pricing

Get the dated public pricing snapshot

Returns gateway base rates in USD per 1M text tokens. Account-group multipliers can change the effective charge.

Access: Public Responses: 200

GET/api/v1/status-metrics.json

Get the current public operational snapshot

Returns sampled public-contract checks and aggregate completion latency. Null success-rate and uptime fields mean the available denominator or sampling interval is not sufficient for a defensible percentage.

Access: Public Responses: 200 500

Chat request fields

Field	Required	Purpose
`model`	Yes	Exact route ID.
`messages`	Yes	Ordered role/content messages.
`stream`	No	Return SSE chunks when true.
`temperature`, `top_p`	No	Sampling controls; route support can vary.
`max_tokens`	No	Output ceiling; respect the selected route's limit.
`tools`, `tool_choice`	No	Tool definitions and selection policy where supported.
`response_format`	No	Structured output request where supported.

Error handling

Code	Meaning	Application action
400	Invalid request shape or unsupported field.	Log the request ID, validate JSON, model ID, and route-specific fields. Do not retry unchanged.
401	Missing, invalid, or revoked key.	Check the bearer header and key status. Do not expose the key in logs.
402	Insufficient balance or quota.	Stop automatic retries, inspect the ledger, then top up or reduce the request.
403	Account, key, group, or policy restriction.	Confirm key scope and account access before retrying.
429	Rate or concurrency limit.	Use exponential backoff with jitter and cap the retry budget.
500	Gateway or upstream failure.	Retry only idempotent work, preserve the request ID, and use a tested fallback if the workload allows it.

delay = min(30, 2 ** attempt) + random.uniform(0, 0.5)
retry only for 429 or transient 5xx
never retry 400, 401, 402, or 403 unchanged