Speech generation

For file inputs, upload through the Files API, then reference the returned file_id. The gateway converts the input; provider acceptance is determined upstream.

Reference assets with input_references: [{"type":"audio","role":"reference","source":{"type":"file","file_id":"..."}}]. Type must match the image/audio/video file. The gateway reads the file and passes it to the selected provider in the form its API expects, keeping the role unchanged. Existing required fields remain required. For Images, Video and Speech, input_references is an InOneAPI extension.

POST /v1/audio/speech follows the OpenAI Speech JSON contract and returns audio bytes, not JSON.

Required fields are model, input, and voice. Optional fields are instructions, response_format (mp3, opus, aac, flac, wav, pcm), speed (0.25–4), and stream_format (audio or sse). Do not send the Chat-style stream field.

Minimal request

Replace YOUR_MODEL_ID with the exact model detail ID; do not add a provider prefix. Optional parameters and voices depend on the selected model. App attribution headers are commented out.

# -H "X-APP-NAME: Your App Name"
# -H "X-APP-URL: https://your-app.example.com"
curl "https://api.inoneapi.com/v1/audio/speech" \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "YOUR_MODEL_ID",
  "input": "Hello from InOneAPI",
  "voice": "REPLACE_WITH_SUPPORTED_VOICE",
  "response_format": "mp3"
}' \
  --output speech.mp3

Parameter reference

Field	Type	Details
model	string	Required public model ID; the platform substitutes the provider model ID when forwarding. Examples use a placeholder: select an available console model.
input	string	Required nonempty text. Provider limits apply; no splitting, truncation, concatenation or SSML conversion.
voice	string/object	Required nonempty voice name or supported custom voice `{"id":"voice_123"}`. Names and account permissions are provider-specific.
instructions	string	Optional delivery/style instructions, only for supporting models. Not a replacement for input.
response_format	string	Defaults to mp3. Models with a fixed output only accept that format. Not url, base64 or json.
speed	number	0.25–4; omitted values use upstream defaults, which may have tighter limits.
stream_format	string	Defaults to audio. SSE requires model support. Chunked audio transfer is not SSE.

Keep keys server-side, and clearly disclose AI-generated speech to listeners. This endpoint does not provide transcription, translation, Realtime or voice training.

Client examples

curl  https://api.inoneapi.com/v1/audio/speech \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "YOUR_MODEL_ID","input": "Hello!","voice": "REPLACE_WITH_SUPPORTED_VOICE","response_format": "mp3"}' \
  --output speech.mp3

Check cURL's exit status: --fail-with-body may save error JSON into speech.mp3. Do not play error responses as audio. A successful response must not be read with response.json(). JavaScript and TypeScript buffer the complete file; use a response stream for large files. Python can save in chunks and raises HTTPError for non-success responses:

Audio and streaming

Format	MIME and requirements
mp3	audio/mpeg; default format.
opus	audio/ogg; the provider must actually return Ogg Opus.
aac	audio/aac; verify upstream packaging and playback support.
flac	audio/flac; lossless and potentially larger.
wav	audio/wav; includes a container header, with provider-specific sample parameters.
pcm	application/octet-stream; headerless. Confirm sample rate, bit depth, channels and endianness. Renaming to WAV does not add a header.

Provider bytes and MIME are returned as received. Audio delivered as Base64 carries a declared MIME but is neither transcoded nor validated against a codec. The non-SSE path may initially buffer audio; immediate byte-by-byte forwarding is not guaranteed.

curl -N https://api.inoneapi.com/v1/audio/speech \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","input":"Hello!","voice":"REPLACE_WITH_SUPPORTED_VOICE","stream_format":"sse"}'

SSE uses text/event-stream. Parse provider events and audio fragments; never save the entire SSE text as MP3. A model without SSE support returns 400 PROTOCOL_STREAM_UNSUPPORTED.

Error reference

Error	Action
400 INVALID_REQUEST_BODY	Check required fields, types, speed and enums; remove stream.
400 PROTOCOL_TRANSFORM_FAILED	A parameter the model does not accept, or a missing value.
400 AUDIO_FORMAT_UNSUPPORTED	Requested format differs from fixed format; omission means mp3.
401/403	Check credentials, permissions and model restrictions.
429	Respect Retry-After and inspect limits/budgets.
502 PROTOCOL_RESPONSE_TRANSFORM_FAILED	Provider audio is invalid or the response exceeded the size cap.

A failed request never produces audio. A timeout may happen after generation and charging: avoid indefinite retries. Retain X-Gateway-Trace-ID, not secrets or sensitive spoken text. No URL downloading, transcoding or task polling is implemented.

Successful MIME types are commonly audio/mpeg, audio/ogg, audio/aac, audio/flac, audio/wav, or application/octet-stream for headerless PCM. Models that support SSE accept stream_format=sse; others reject it. 400 means invalid parameters or format, 429 requires Retry-After handling, and 502 means the provider response could not be parsed or exceeded the size limit.

Try in the playground

The console Playground and model detail “Try now” panel support audio output with a voice and MP3/WAV/Opus/AAC/FLAC selection, playback and saving. The selected model must support the voice and encoding; a model with a fixed output requires the matching request format. Raw PCM playback is not offered, and speech responses are consumed as audio bytes rather than Chat JSON.