Create a Chat Completion

POST/v1/chat/completions

API Access

Use the same AudioLab API URL as your other model requests. Confirm the model is enabled and your key has llm.write access. See the Text setup guide.

Overview

Looking for generated audio? See the audio-output profile on this endpoint.

Generate a chat completion from conversation messages, with supported tools, images and PDFs, web search, routing, and optional SSE.

Routing and provider details

A funded workspace and llm.write key are required. Send an Idempotency-Key for each logical request; retries use that same key. Options depend on the selected model profile: a sampling parameter the answering model does not support, such as temperature, top_p, seed or stop, is dropped and named in the x-audiolab-dropped-params header. Every response explains its route in the x-audiolab-routing header (JSON) and the body's routing field, on the final chunk of a stream. A stream whose candidates all fail before any output returns an HTTP error instead of an error event. Audio output has a separate profile documented below. General inference remains gated by managed accounting readiness.

Authorization

Authorizationstring · headerRequired

AudioLab API key sent as Bearer <token>. Authentication guide

Parameters

x-audiolab-cacheheader · string

true stores a successful answer and serves an identical later request from your workspace with no provider call and no charge (usage.cost 0, usage.cache_hit true). The x-audiolab-cache-status response header reads HIT, MISS or BYPASS; zero data retention always bypasses. X-OpenRouter-Cache is accepted too.

x-audiolab-cache-ttlheader · integer

Seconds an answer stays cached, 1 to 86400. Default 300.

x-audiolab-cache-clearheader · string

true replaces the cached answer with a fresh one.

Request Body

application/json

modelstringRequired

Model ID from List Models, costream/auto, costream/fusion, or a named router as router/<id>. A model that several hosts serve routes across them; a host’s own ID selects that host. Add :nitro, :floor or :exacto to rank its hosts by throughput, price or tool-call validity, :free to keep free hosts, or :thinking to keep hosts that reason; an unknown suffix is refused. A ~author/family-latest alias, such as ~z-ai/glm-latest, selects the newest model of that family.

messagesobject[]Required

Conversation messages with roles and content. User content may mix text, image_url and file (PDF) parts, by https URL or base64 data URI, for models whose input_modalities list them.

Show nested fields

object

max_tokensinteger

Maximum generated output tokens, up to the model’s output cap (top_provider.max_completion_tokens in List Models). Optional: without it the model may write up to that cap, within the context left, and you pay for the tokens it writes.

streamboolean

Return protocol-specific server-sent events.

Default: false

toolsobject[]

Client-defined function tools, which the application executes, and openrouter:web_search or web_search to turn on the model’s own search.

Show nested fields

object

modelsstring[]

Fallback models, tried in order when the one before fails before any output. Each must support the request’s tools, response format and reasoning settings.

Show nested fields

string

providerobject

OpenRouter provider preferences. only, ignore and order take provider names or slugs, or an endpoint tag such as deepinfra/turbo. sort (price, throughput, latency or exacto, with partition model or none), allow_fallbacks, quantizations, max_price, preferred_min_throughput, preferred_max_latency, zdr and data_collection are honoured; zdr and data_collection can only narrow your workspace’s privacy settings. data_region (us, eu or a country code, or a list of them) routes only to endpoints documented as processing there, fallbacks included; it can narrow the workspace’s Data Region but never widen it, and a request no endpoint can serve is refused with 400 data_region_unavailable. require_parameters: true refuses a request whose sampling parameters the model does not support, or a named router does not let requests override, instead of dropping them. enforce_distillable_text and options are accepted but not honoured, and are named in the x-audiolab-ignored-provider-fields header.

pluginsobject[]

auto-router (allowed_models, cost_quality_tradeoff) with costream/auto; fusion (analysis_models, preset, model); web (the model’s own web search); file-parser (pdf.engine: native, pdf-text or mistral-ocr; max_files); response-healing (repairs a non-streamed JSON answer); context-compression (middle-out).

Show nested fields

object

transformsstring[]

middle-out removes messages from the middle of a conversation until it fits the smallest context among the requested model and its fallbacks.

Show nested fields

string

web_search_optionsobject

Turns on the model’s own web search. search_context_size and user_location apply on OpenAI models.

router_revisioninteger

Named routers only: the published revision to use. Without it, the router’s current revision applies.

Minimum 1 · Maximum 1000

metadataobject

Named routers only: up to 32 string, number or boolean values that the router’s conditions match as metadata.<key>. Keys start with a letter; strings are at most 512 characters.

service_tierstring

flex (cheaper, slower) or priority (faster) on OpenAI and Gemini models with a reviewed price for that tier, charged at that tier’s rate; the response’s service_tier names the tier that served it. Elsewhere the tier is dropped and named in x-audiolab-dropped-params, or refused under provider.require_parameters. auto and default use the standard tier.

Values: "auto""default""flex""priority"

ninteger

Completions to return for one model, without models, plugins or a router. Each is charged and the hold scales with n. Streaming n above 1 needs a model that returns several completions in one call, such as OpenAI’s.

Default: 1

Minimum 1 · Maximum 8

cache_controlobject

Anthropic prompt caching: {"type": "ephemeral"} here caches the prompt up to the last message; the same marker on a text part, system block or tool sets a breakpoint, at most 4. Writes and reads are charged at the model’s cache rates and reported in usage. A one-hour ttl is sent as five minutes. OpenAI and Gemini cache automatically, so the marker is accepted and named in x-audiolab-dropped-params.

session_idstring

Keeps a session on one route: costream/auto reuses the model it chose (without session_id it recognises a conversation by its first messages), and a named router assigns the same A/B variant (without it, each request is assigned afresh).

Responses

200Completed response or SSE stream when stream is true.

application/json

object

400Invalid or unsupported request contract. A named router’s refusal keeps its message and param.

401Invalid gateway credential.

402Insufficient credits.

404Unknown named router or revision.

409This idempotency key already identifies a request; provider inference is not repeated.

422A named router’s revision cannot run under current policy.

429Rate or concurrency limit.

502Every candidate failed with a provider error before any output, on a stream as well.

503Inference disabled or managed accounting not ready.

Audio Output

The same Chat Completions path also supports a restricted audio-output profile. Select this profile with its model ID and audio fields. Its schema and limits below apply instead of the general text profile.

This entry documents the dedicated openai/gpt-audio-1.5-chat profile on the enabled LLM gateway. It sends one plain user string, up to 4096 UTF-8 bytes, to native gpt-audio-1.5 and returns text plus alloy WAV audio in JSON. Requires a funded workspace and a key with llm.write. Also available under /api/v1.

Set modalities to ["text", "audio"] and audio to {"voice":"alloy","format":"wav"}. The effective output cap is fixed at 16384. An explicit max_tokens or max_completion_tokens must equal 16384; omission uses that value. The example sets max_tokens explicitly. Streaming, input audio, conversation history, tools, plugins, fallbacks, custom voices and sampling overrides are rejected for this profile. These audio options do not apply to other Chat models.

The response preserves choices[0].message.audio.id, data, expires_at and transcript. data is base64-encoded WAV; expires_at is the native Unix timestamp. Inclusive prompt/completion usage includes separate audio and text token counters. Native token expense minus 15% determines the charge. A hold covers the full reviewed model bounds before one native request; missing or invalid output/usage retains the hold without a retry. This profile remains subject to deployment, credential and admission gates.

Audio Request

curl --fail --show-error --request POST \
  --url "$AUDIOLAB_API_URL/v1/chat/completions" \
  --header "Authorization: Bearer $AUDIOLAB_API_KEY" \
  --header 'Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-audio-1.5-chat",
  "messages": [
    {
      "role": "user",
      "content": "Say hello."
    }
  ],
  "max_tokens": 16384,
  "stream": false,
  "modalities": [
    "text",
    "audio"
  ],
  "audio": {
    "voice": "alloy",
    "format": "wav"
  }
}'

application/json

modelstringRequired

messagesobject[]Required

Show nested fields

rolestringRequired

contentstringRequired

Nonblank plain text, at most 4096 UTF-8 bytes.

max_tokensinteger

Default: 16384

max_completion_tokensinteger

Alternative name for the same fixed output cap.

streamboolean

Default: false

modalitiesstring[]Required

Show nested fields

string

audioobjectRequired

Show nested fields

voicestringRequired

formatstringRequired

Audio Responses

{
  "choices": [
    {
      "message": {
        "role": {},
        "content": {},
        "audio": {}
      }
    }
  ],
  "usage": {}
}

200Completed JSON Chat response with native audio and validated token usage.

application/json

choicesobject[]Required

Show nested fields

messageobjectRequired

Show nested fields

rolestringRequired

contentstring | null

audioobjectRequired

Show nested fields

See the OpenAPI schema for this nested object.

usageobjectRequired

Inclusive native token totals and prompt/completion audio and text subsets.

400Invalid or unsupported audio Chat request.

401Invalid gateway credential.

402Insufficient credits for the full reservation.

403Key or workspace restrictions.

409Duplicate idempotency key; provider inference is not repeated.

429Rate or concurrency limit.

503Disabled admission or unresolved native output/usage; unknown attempts retain their hold.