Audio API guide

Use POST /v1/audio/speech to turn text into speech. Send JSON and receive audio bytes by default, not a Chat message, JSON download link, or async task. For audio understanding with text output, choose an audio-capable text model and endpoint.

Model, voice, and format

Choose a public model with an audio mapping and replace YOUR_MODEL_ID and REPLACE_WITH_SUPPORTED_VOICE. Voice names are provider-specific; use a supported name or custom voice ID. Set INONEAPI_API_KEY on the server.

Field	Usage
`model`	Required public model ID.
`input`	Required nonempty text; no automatic splitting, truncation, or SSML conversion.
`voice`	Required nonempty name or a supported `{"id":"voice_123"}` object.
`instructions`	Optional style or emotion instructions for supporting models.
`response_format`	Default mp3; must match model or fixed-format mapping capabilities.
`speed`	Optional 0.25–4; providers can impose tighter limits.
`stream_format`	Default `audio`; `sse` only on native channels supporting it.

Generate and save audio

This Node.js 20+ example checks HTTP status, streams into a temporary file, renames on success, and cleans partial output on failure. It uses fixed names for one task; concurrent applications need a unique temporary path per request.

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":"Welcome to InOneAPI.","voice":"REPLACE_WITH_SUPPORTED_VOICE","response_format":"mp3"}' \
  --output speech.mp3

cURL --fail-with-body can write error JSON into speech.mp3; check its exit status before playback. Do not call response.json() on successful binary output. Actual bytes determine duration and encoding.

Output formats

Format	Typical MIME	Notes
mp3	`audio/mpeg`	Default, widely playable.
opus	`audio/ogg`	Ensure Ogg Opus support.
aac	`audio/aac`	Container compatibility depends on provider and player.
flac	`audio/flac`	Lossless, often larger.
wav	`audio/wav`	Has a container header; inspect actual sample parameters.
pcm	`application/octet-stream`	Raw samples; requires sample rate, bit depth, channels, and endianness.

The gateway does not transcode. Renaming PCM to WAV does not add a header. Fixed-format Base64 mappings accept only their configured format; omission is validated as mp3, not automatic format negotiation.

Reference audio

Only explicitly compatible models and mappings support this extension. Upload first and call Speech using the same key:

{
  "model": "YOUR_MODEL_ID",
  "input": "Welcome to InOneAPI.",
  "voice": "REPLACE_WITH_SUPPORTED_VOICE",
  "response_format": "mp3",
  "input_references": [
    {
      "type": "audio",
      "role": "reference",
      "source": {
        "type": "file",
        "file_id": "file_ioa_0123456789abcdef0123456789abcdef"
      }
    }
  ]
}

input_references is not a native OpenAI Speech field. It does not automatically provide voice cloning, voice registration, or transcription. type must match audio and the mapping must support the role. The gateway converts the file to a signed URL and preserves the role. input, voice, and model remain required.

Streaming

The default stream_format: audio returns audio bytes. HTTP chunking is not SSE and does not guarantee immediate byte-by-byte forwarding. The save example applies to this mode.

On native channels supporting stream_format: sse, parse provider-specific events and audio chunks; do not save the SSE text itself as MP3. Do not send Chat's stream field. DSL conversion and Base64 audio extraction do not support SSE and return PROTOCOL_STREAM_UNSUPPORTED.

Limits and errors

For 400 INVALID_REQUEST_BODY, check required fields, format, and speed; for AUDIO_FORMAT_UNSUPPORTED, check fixed formats; for 502 PROTOCOL_RESPONSE_TRANSFORM_FAILED, check upstream JSON/Base64 and buffer limits. For 401/403, check access; for 429, honor Retry-After and bound concurrency.

This endpoint does not provide transcription, translation, Realtime, task queries, or automatic stitching. Split long text in your application according to model limits and handle voice consistency and concatenation. Timeouts may occur after generation and billing; avoid endless retries. Record X-Gateway-Trace-ID, omit sensitive speech text from logs, and disclose AI-generated audio to end users.

POST /v1/audio/speech · POST /v1/files · Text guide