Skip to content
Documentation
GuidesAPI ReferenceIntegrations
ArenaPlatform
API Reference/Realtime Audio

Create a Conversation Turn

POST/v1/audio/speech-to-speech

Overview

Sends one recorded utterance to an OpenAI Realtime model and returns the spoken reply as WAV or raw PCM16 at 24000 Hz, with its transcript and the settled usage. Requires an audio.write key and a deployment with REALTIME_ENABLED. Each request is a new conversation; use the WebSocket stream to keep context across turns.

Models: openai/gpt-realtime-2.1-mini, openai/gpt-realtime-2.1, openai/gpt-realtime-2 and openai/gpt-realtime-1.5. Routing aliases such as s2s/auto are not available.

input_audio is base64 mono 16-bit PCM at 24000 Hz, 0.1 to 60 seconds: a WAV file (format: wav) or raw little-endian samples (format: pcm16, sample_rate: 24000). Other formats, sample rates and channel counts are rejected. temperature, feature and other fields have no reviewed price and return 422; provider takes only data_region.

Before connecting to OpenAI, the request holds the model's full context at its highest input rate plus max_output_tokens at its highest output rate, minus 15%. At the default 1024-token cap that is about USD 3.54 for 2 and 2.1, 1.11 for 2.1 Mini and 0.93 for 1.5. The response returns after OpenAI's final usage is recorded: the charge is that usage at OpenAI's published text, audio and cached rates minus 15%, and the rest of the hold is released. Reasoning tokens are part of the text output. Per workspace, at most four turns can be unsettled, twenty can start per minute, and known expense plus open holds is limited to USD 20 a day, shared with the WebSocket.

With stream: true the response is text/event-stream. Each event's data is JSON with a type: response.created, then output_audio.delta (base64 PCM16 at 24000 Hz) and output_transcript.delta as they arrive, then response.done with the settled usage, or error. Streamed audio counts as delivered: a response cancelled or failed after a delta is charged for its known usage. A buffered request whose client disconnects first is cancelled and not charged.

A reused Idempotency-Key (1 to 160 printable ASCII characters) never generates again; it returns 409 naming the original request. Audio is not stored. If OpenAI's final usage is lost, the error names the request and its hold stays until resolved; check GET /v1/requests/{request_id} before retrying.

Authorization

Authorizationstring · headerRequired

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

Parameters

Idempotency-Keyheader · string

Optional key, 1 to 160 printable ASCII characters. A reuse returns 409 instead of a second generation.

Request Body

application/json
providerobject

Provider preferences for a single-endpoint product.

Show nested fields
data_regionstring | string[]

Route only to endpoints documented as processing in this region: us, eu (which includes EU member states), or a country code such as nl, sg, in or cn. A list matches any of its regions. Endpoints whose region is global or unknown never match; global on its own means no requirement. The request's region narrows the workspace's Data Region and a named router's region policy, and never widens them. Fallbacks keep to it. When no endpoint qualifies, the request is refused with 400 data_region_unavailable, param provider.data_region.

Show nested fields
Option 1: string

string

Option 2: string[]

See the OpenAPI schema for this nested object.

modelstringRequired

Values: "openai/gpt-realtime-2.1-mini""openai/gpt-realtime-2.1""openai/gpt-realtime-2""openai/gpt-realtime-1.5"

input_audioobjectRequired
Show nested fields
datastringRequired

Base64 audio without a data-URL prefix. Mono 16-bit PCM at 24000 Hz, 0.1 to 60 seconds.

formatstringRequired

wav is a WAV file; pcm16 is raw little-endian 16-bit mono samples.

Values: "wav""pcm16"

sample_rateinteger

Required for pcm16 and must be 24000. A WAV file's header must also say 24000.

channelsinteger

Default: 1

output_audioobject
Show nested fields
formatobject

Defaults to wav, or pcm16 when streaming. Streamed audio is always pcm16.

Show nested fields

wav is a WAV file; pcm16 is raw little-endian 16-bit mono samples.

sample_rateinteger
voicestring

auto uses marin.

Values: "auto""alloy""ash""ballad""coral""echo""sage""shimmer""verse""marin""cedar"

Default: "auto"

instructionsstring

System guidance for the reply, up to 4096 UTF-8 bytes. Defaults to "Answer briefly."

max_output_tokensinteger

Cap on audio, transcript and reasoning tokens. A reply that reaches it ends with status incomplete.

Default: 1024

Minimum 1 · Maximum 1024

streamboolean

Send the reply as server-sent events instead of one JSON body.

Default: false

Responses

200The turn completed and was settled.
application/json
idstringRequired

Request ID, also returned in x-request-id.

objectstringRequired
createdintegerRequired

Unix timestamp in seconds.

modelstringRequired
providerstringRequired
statusstringRequired

incomplete when the reply reached max_output_tokens.

Values: "completed""incomplete"

audioobjectRequired
Show nested fields
datastringRequired
formatstringRequired

wav is a WAV file; pcm16 is raw little-endian 16-bit mono samples.

Values: "wav""pcm16"

content_typestringRequired

Values: "audio/wav""audio/pcm"

sample_rateintegerRequired
channelsintegerRequired
transcriptstring | nullRequired

Text of the spoken reply.

usageobjectRequired
Show nested fields
input_tokensintegerRequired

Minimum 0

output_tokensintegerRequired

Minimum 0

input_audio_tokensintegerRequired

Minimum 0

input_text_tokensintegerRequired

Minimum 0

input_cached_audio_tokensintegerRequired

Minimum 0

input_cached_text_tokensintegerRequired

Minimum 0

output_audio_tokensintegerRequired

Minimum 0

output_text_tokensintegerRequired

Minimum 0

output_reasoning_tokensinteger

Present when OpenAI reports it; already counted in output_text_tokens.

Minimum 0

costnumberRequired

USD charged for this turn.

Minimum 0

currencystringRequired
text/event-stream

With stream true, response.created, output_audio.delta, output_transcript.delta and response.done or error events.

400Request validation failed.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

401Authentication is missing or invalid.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

402Credits or billing setup is required.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

403Authenticated principal lacks permission.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

409Request conflicts with current resource state.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

413The request body exceeds 38,194,304 bytes.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

415Audio format is unsupported.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

422Audio could not be processed.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

429Rate limit exceeded.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

500Internal server error.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

502Upstream provider failed after allowed attempts.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

503No eligible provider endpoint is currently available, or async processing has no healthy worker polling the durable queue.
application/json
errorobjectRequired
Show nested fields
codestringRequired
messagestringRequired
paramstring | null
request_idstring | null
metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.