Audio API Reference

Use AvalAI audio endpoints to transcribe speech, translate speech to English, generate spoken audio, or add direct audio input/output to a Chat Completions flow. AvalAI uses an OpenAI-compatible base URL, so OpenAI SDK examples work when you set base_url / baseURL to https://api.avalai.ir/v1 and authenticate with AVALAI_API_KEY.

Related guides: Audio processing, Realtime and live audio, Speech to text, Text to speech, Responses vs Chat Completions

Choose an Audio Path

Goal	AvalAI path	Use when
Generate spoken audio from text	POST /v1/audio/speech	You have final text and need an audio file or streamable response.
Transcribe or translate a file	POST /v1/audio/transcriptions, POST /v1/audio/translations	You have a bounded audio file or upload.
Direct audio input/output in a chat app	POST /v1/chat/completions with an audio-capable model	You need input_audio, modalities, or message.audio in the same model call.
Responses-first voice workflow	/v1/audio/transcriptions → /v1/responses → /v1/audio/speech	You want Responses reasoning, tools, structured output, or state handling around audio.
Low-latency live voice sessions	Realtime architecture reference	OpenAI Realtime docs are useful for architecture planning; use AvalAI-supported request-based endpoints unless a Realtime route is enabled for your account.

OpenAI's current guidance separates request-based audio APIs from Realtime sessions. Request-based APIs are simpler for files and generated speech; Realtime sessions are for live, low-latency audio events. AvalAI examples below focus on supported request-based and Chat Completions paths.

Text-to-Speech

Endpoint

POST https://api.avalai.ir/v1/audio/speech

Request Body

Parameter	Type	Required	Notes
model	string	Yes	Supported IDs include gpt-4o-mini-tts, tts-1, tts-1-hd, gemini-2.5-pro-tts, gemini-2.5-flash-tts, gemini-2.5-pro-preview-tts, gemini-2.5-flash-preview-tts, eleven_v3, eleven_multilingual_v2, eleven_turbo_v2, eleven_turbo_v2_5, eleven_flash_v2, eleven_flash_v2_5, groq.playai-tts, and groq.playai-tts-arabic. Check model details for current availability.
input	string	Yes	Text to synthesize. OpenAI-compatible TTS accepts up to 4,096 characters per request; provider-specific routes may set different limits, so split long scripts by paragraph or scene.
voice	string	Yes	OpenAI voices include alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse, marin, and cedar; evaluate marin or cedar first when voice quality matters. Provider-specific models may expose different voices. Custom voice objects are not a general AvalAI feature unless enabled for your account.
instructions	string	No	Style guidance for compatible models such as gpt-4o-mini-tts; not supported by every model and not supported by tts-1 / tts-1-hd in OpenAI's reference behavior.
response_format	string	No	mp3 by default. Common formats: mp3, opus, aac, flac, wav, pcm. Use wav or pcm for lower playback latency.
speed	number	No	Playback speed when supported by the selected model. OpenAI-compatible Speech accepts 0.25 to 4.0, with 1.0 as the default.
stream_format	string	No	Streaming envelope when supported. OpenAI-compatible values are audio and sse; sse is not supported by tts-1 / tts-1-hd.

Basic Speech Generation

Bash

curl https://api.avalai.ir/v1/audio/speech \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "voice": "coral",
    "input": "Today is a wonderful day to build something people love.",
    "instructions": "Speak in a warm, confident tone."
  }' \
  --output avalai_speech.mp3

Python

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

speech_path = Path("avalai_speech.mp3")

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    voice="coral",
    input="Today is a wonderful day to build something people love.",
    instructions="Speak in a warm, confident tone.",
) as response:
    response.stream_to_file(speech_path)

print(f"Saved {speech_path}")

JavaScript

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const audio = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "coral",
  input: "Today is a wonderful day to build something people love.",
  instructions: "Speak in a warm, confident tone.",
});

await fs.writeFile("avalai_speech.mp3", Buffer.from(await audio.arrayBuffer()));

TTS Notes

• Keep tts-1 and tts-1-hd for compatibility with older integrations; use gpt-4o-mini-tts when you need richer voice instructions.
• Voice availability varies by model family. tts-1 and tts-1-hd support a smaller OpenAI voice set than gpt-4o-mini-tts; if a voice fails, switch to a documented voice for that provider.
• Disclose to end users when generated speech is AI-generated.
• Treat OpenAI custom voice creation as an account-specific/provider-specific feature, not a default AvalAI endpoint. Keep consent records for any provider workflow that records or clones a voice.
• For long scripts, split text into sections and stitch the returned audio files in your application.

Speech-to-Text: Transcription

Endpoint

POST https://api.avalai.ir/v1/audio/transcriptions

Request Body

Parameter	Type	Required	Notes
file	file	Yes	Audio file upload. For OpenAI-compatible transcription models, keep files at or below 25 MB and use formats such as flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. Split or compress longer audio.
model	string	Yes	Supported IDs include whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, scribe_v1, scribe_v2, groq.whisper-large-v3, and groq.whisper-large-v3-turbo.
language	string	No	Optional ISO-639-1 language hint, such as en or fa, when supported. Supplying the input language can improve accuracy and latency.
prompt	string	No	Context hint for spelling, vocabulary, or style. Not supported by every transcription model; OpenAI's diarization model does not support prompt.
response_format	string	No	json by default. whisper-1 supports json, text, srt, verbose_json, and vtt; GPT-4o transcription models commonly support json or text; diarization can use diarized_json.
timestamp_granularities[]	array	No	Word or segment timestamps for compatible models, especially whisper-1 with verbose_json; word timestamps can add latency and this option is not available for OpenAI's diarization model.
stream	boolean	No	Streams transcript events for compatible non-Whisper models. Expect transcript.text.delta events and a final transcript.text.done; diarized streams can also emit transcript.text.segment. OpenAI's whisper-1 does not support streamed transcription. Use Realtime only when your account has a supported live-audio route.
chunking_strategy	string or object	No	Required by OpenAI diarization for inputs longer than 30 seconds. Use "auto" unless you need a provider-specific VAD configuration.
include[]	array	No	Use include[]=logprobs with response_format="json" on compatible GPT-4o transcription models to inspect token-level confidence. Not supported by whisper-1 or OpenAI's diarization model.
temperature	number	No	Sampling temperature from 0 to 1 when supported. Lower values are more deterministic; 0 lets the service adjust from log probability thresholds.
known_speaker_names[] / known_speaker_references[]	arrays	No	Optional named-speaker mapping for compatible diarization routes. OpenAI supports up to 4 speakers; reference clips should be 2–10 seconds and encoded as data URLs.

Transcribe an Audio File

Bash

curl https://api.avalai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@meeting.mp3" \
  -F model="gpt-4o-transcribe" \
  -F response_format="text"

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with open("meeting.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=audio_file,
        response_format="text",
        prompt="Product names include AvalAI, Qwen, Grok, Claude, and Gemini.",
    )

print(transcript)

JavaScript

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const transcript = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("meeting.mp3"),
  response_format: "text",
  prompt: "Product names include AvalAI, Qwen, Grok, Claude, and Gemini.",
});

console.log(transcript);

Speaker Diarization

Use gpt-4o-transcribe-diarize when you need speaker-aware segments. Request diarized_json; set chunking_strategy: "auto" for recordings longer than 30 seconds. In OpenAI's current docs this model is only available through /v1/audio/transcriptions, not Realtime.

Bash

curl https://api.avalai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@meeting.wav" \
  -F model="gpt-4o-transcribe-diarize" \
  -F response_format="diarized_json" \
  -F chunking_strategy="auto"

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with open("meeting.wav", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe-diarize",
        file=audio_file,
        response_format="diarized_json",
        chunking_strategy="auto",
    )

for segment in transcript.segments:
    print(segment.speaker, segment.start, segment.end, segment.text)

Streaming Transcription Events

For completed file uploads, set stream=true on compatible GPT-4o transcription models when you want transcript text as soon as each part is ready. Handle these event types:

• transcript.text.delta: partial transcript text. Diarized streams may include a segment_id, but speaker labels are finalized later.
• transcript.text.done: final transcript text and usage metadata.
• transcript.text.segment: finalized diarized segment with speaker, start, end, and text.

If confidence scoring matters, request include[]=logprobs with response_format="json" on supported GPT-4o transcription models. Do not enable streaming for whisper-1; use file chunks or a Realtime route instead.

Speech-to-Text: Translation

Endpoint

POST https://api.avalai.ir/v1/audio/translations

The translation endpoint accepts supported audio input and returns English text. Use whisper-1 unless your account has another translation-capable model enabled.

Request Body

Parameter	Type	Required	Notes
file	file	Yes	Audio file upload in a supported format such as flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. Keep OpenAI-compatible uploads at or below 25 MB.
model	string	Yes	OpenAI's translation endpoint supports whisper-1; use another model only when AvalAI has explicitly enabled a translation-capable route for your account.
prompt	string	No	Optional context hint. Match the source audio language when possible.
response_format	string	No	json by default. Common OpenAI-compatible formats include json, text, srt, verbose_json, and vtt.
temperature	number	No	Sampling temperature from 0 to 1 when supported. Lower values are more deterministic.

Bash

curl https://api.avalai.ir/v1/audio/translations \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@german.mp3" \
  -F model="whisper-1"

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with open("german.mp3", "rb") as audio_file:
    translation = client.audio.translations.create(
        model="whisper-1",
        file=audio_file,
    )

print(translation.text)

Audio in Chat Completions

Audio-capable chat models such as gpt-audio-1.5, gpt-audio, and gpt-audio-mini support direct audio input and/or audio output in /v1/chat/completions. Keep this path when you need the model to return message.audio or accept input_audio directly.

Bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-audio-mini",
    "modalities": ["text", "audio"],
    "audio": { "voice": "alloy", "format": "wav" },
    "messages": [
      { "role": "user", "content": "Explain our refund policy in a friendly voice." }
    ]
  }'

Python

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

completion = client.chat.completions.create(
    model="gpt-audio-mini",
    modalities=["text", "audio"],
    audio={"voice": "alloy", "format": "wav"},
    messages=[
        {"role": "user", "content": "Explain our refund policy in a friendly voice."}
    ],
)

audio_data = completion.choices[0].message.audio.data
with open("reply.wav", "wb") as output:
    output.write(base64.b64decode(audio_data))

Responses migration path: transcribe or write text with `/v1/responses`, then render speech with `/v1/audio/speech`.

The Responses API is recommended for new text, reasoning, tool, and stateful workflows, but direct audio input/output should stay on Chat Completions when you need input_audio or message.audio. For a Responses-first voice workflow, use a pipeline:

1. Transcribe user audio with /v1/audio/transcriptions.
2. Send the transcript to /v1/responses.
3. Read response.output_text.
4. Generate spoken output with /v1/audio/speech.

Python

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with open("question.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=audio_file,
        response_format="text",
    )

response = client.responses.create(
    model="gpt-5.5",
    instructions="Answer clearly and briefly for a spoken support assistant.",
    input=transcript,
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    voice="coral",
    input=response.output_text,
) as speech:
    speech.stream_to_file(Path("answer.mp3"))

JavaScript

import fs from "node:fs";
import fsp from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const transcript = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("question.mp3"),
  response_format: "text",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: "Answer clearly and briefly for a spoken support assistant.",
  input: transcript,
});

const speech = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "coral",
  input: response.output_text,
});

await fsp.writeFile("answer.mp3", Buffer.from(await speech.arrayBuffer()));

Error Handling

Status	Common cause	Fix
400	Unsupported parameter for the selected model	Remove model-specific fields such as unsupported instructions, timestamps, diarization, or audio modalities.
401	Missing or invalid API key	Set AVALAI_API_KEY and avoid hard-coding secrets.
413	Audio upload too large	Compress, split the file, or use shorter chunks.
415	Unsupported media type	Use common audio formats such as flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm for OpenAI-compatible transcription models.
429	Rate limit exceeded	Retry with backoff and check your tier limits.

Best Practices

• Use gpt-4o-transcribe or gpt-4o-mini-transcribe for higher-quality file transcription; keep whisper-1 for broad compatibility, timestamps, and translations.
• Use gpt-4o-transcribe-diarize only when speaker labels are required.
• Use include[]=logprobs on supported GPT-4o transcription models when you need confidence signals for review queues or QA.
• Prefer gpt-4o-mini-tts for controllable TTS; keep tts-1 and tts-1-hd for existing integrations.
• Use Chat Completions for direct audio-in/audio-out model calls.
• Use Responses for transcript reasoning, tool use, structured output, and multi-turn state, then send final text to TTS.
• Log model IDs, latency, upload size, and response format for debugging and cost review.
• Use Speaker-Aware Meeting Intelligence when downstream decisions and action items need mechanically validated transcript evidence.