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":"image","role":"reference","source":{"type":"file","file_id":"..."}}]. Type must match the image/audio/video file. The gateway replaces source with a COS signed URL, preserves role, then applies DSL. Existing required fields remain required. For Images 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

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

Native mode preserves bytes/MIME. Base64 mode declares MIME without transcoding or codec validation. 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. DSL returns 400 PROTOCOL_STREAM_UNSUPPORTED.

Error reference

Upstream errors bypass success transforms. 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. Native providers may support stream_format=sse; request DSL and Base64 extraction do not. 400 means request or mapping validation failed, 429 requires Retry-After handling, and 502 means response conversion failed or exceeded the default 32 MiB buffer.

In Mapping Management select Audio API and configure audio_path. Native mode is enabled by default; disable it to edit request DSL and optional audio_response. See docs/audio-protocol-dsl.md and docs/audio-protocol-dsl.schema.json for the complete AI-generation contract, fixtures, edge cases, metering and capability boundaries.

Mapping and billing details

The test button validates structure and generates illustrative cURL only; it does not call a provider. Native mode saves {"version":1}. Audio does not use generic response/retrieve JSON stages.

Metering and billing are separate configurations. Base64 mode reads original upstream JSON usage, not decoded bytes. Binary responses normally lack JSON usage; missing meters do not mean free service. Existing metering DSL does not calculate string length or audio duration. Character/second pricing needs reliable provider meters or a dedicated adapter. The buffer limit includes JSON/Base64 overhead; concurrent memory also includes decoded bytes.

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 fixed-format audio_response DSL requires the matching request format. Raw PCM playback is not offered, and speech responses are consumed as audio bytes rather than Chat JSON.