--- title: "Audio Transcriptions" method: POST path: "/v3/audio/transcriptions" tags: ["Audio"] --- # Audio Transcriptions `POST /v3/audio/transcriptions` ## Request - Base URL: `https://api.edenai.run` - URL: `https://api.edenai.run/v3/audio/transcriptions` - Auth: HTTP bearer OpenAI-compatible speech-to-text endpoint. Accepts either ``multipart/form-data`` (OpenAI SDK shape: a ``file`` upload plus text fields) or ``application/json`` (``file_id`` / ``file_url`` plus text fields). Content-Type drives dispatch. ## Request body - object: JSON request body, references the audio by ``file_id`` or ``file_url``. Exactly one of ``file_id`` (an Eden upload id) or ``file_url`` (an https URL or a ``data:audio/...;base64,...`` URL) must be set. - `tags` unknown - `routing` ProviderRoutingPreferences: How to choose between SELLERS of one model — and, with ``@edenai``, how far to trade quality for cost when the platform chooses the model. ``order``, ``allowed_providers``, ``ignored_providers`` and ``max_price`` shape WHICH sellers and in what order; ``sort`` ranks the rest. The seller fields are only meaningful when `model` is a canonical name (`gpt-5.5`) rather than a concrete `provider/model` — with a concrete id there is nothing to choose between. For choosing the MODEL itself see ``router_candidates`` and ``model="@edenai"``, which is a different router; ``quality_cost`` below is the one field here that speaks to it. - `sort` 'cost' | 'speed' | 'latency' | 'exact', nullable: What to optimise for when several providers serve the requested model. 'cost' (default) picks the cheapest for this request's shape; 'speed' the highest tokens/second; 'latency' the fastest to first token; 'exact' the most reliable at producing well-formed tool calls / structured output. Health is always a filter first — no mode will route you to a failing provider. Can also be written as a model suffix, e.g. 'gpt-5.5:speed'. - `sticky` boolean, nullable: Keep a conversation on the provider holding its prompt cache. On by default, and only ever active for models whose providers discount cache reads. Set false to route every request independently on price instead. Naming an explicit `sort` or an `order` also takes priority over cache affinity. - `allow_fallbacks` boolean, nullable: Whether other providers of the same model may be tried when the chosen one fails. On by default. Set false to pin the request to the single best provider: it then fails rather than silently moving to another seller, useful when a cache-warm prompt would cold-miss elsewhere. This governs PROVIDERS of the requested model only; models you list in `fallbacks` are your own choice and are always kept. - `quality_cost` integer, nullable: Only with model='@edenai': how far to trade answer quality for cost when the platform chooses the MODEL. 0 asks for the best model for the request, 10 for the cheapest model that can still handle it, values in between blend the two; omit it to leave the choice to the platform (quality first). This is the one `routing` field that steers the model rather than the provider — `sort` never changes which model is chosen. - `allowed_providers` string[], nullable: Restrict routing to these providers, e.g. ['openai', 'anthropic']. Only providers that serve the requested model are considered, so an entry that does not sell it is simply inert. If none of them do, the request fails rather than falling back to a provider you excluded. Case-insensitive. Applies to routed providers only. a concrete 'provider/model' you named in `fallbacks` is your own choice and is kept. - `zero_data_retention` boolean, nullable: Serve this request only from providers that keep no prompts or outputs, and save neither its content nor its response. Applies to every model in the request, including a concrete 'provider/model' and your `fallbacks`: one that is not zero data retention fails the request. It can only add the restriction. When your organization requires zero data retention, `false` does not lift it. - `ignored_providers` string[], nullable: Never route to these providers, e.g. ['deepinfra']. The mirror of `allowed_providers`: an entry that does not sell the requested model is inert, and if the list removes every seller the request fails rather than falling back to one you excluded. Case-insensitive. A provider named in both lists is a validation error. A concrete 'provider/model' you named in `fallbacks` is your own choice and is kept. - `order` string[], nullable: Providers to try first, in this order, e.g. ['azure', 'openai']. They become the head of the fallback chain; the remaining providers of the model follow, ranked by `sort` (or load-balanced on price when no `sort` is given). An entry that does not sell the model is inert. A provider our health data marks as down is moved to the end of the chain whatever its position here. Naming an `order` turns cache affinity off, as naming a `sort` does. Case-insensitive. - `max_price` MaxPrice: A price ceiling in USD per MILLION tokens, one bar per direction, either one optional. Unknown keys are refused: a typo on one side (``ouput``) must not silently remove that bar. - `input` number, nullable: Highest input rate accepted, in USD per million tokens. - `output` number, nullable: Highest output rate accepted, in USD per million tokens. - `model` string, required: provider/model, e.g. 'openai/whisper-1' - `language` string, nullable: ISO-639-1 language code of the input audio (e.g. 'en'). Omit to let the provider auto-detect where supported. - `prompt` string, nullable: Optional text to guide the model's style or continue a prior audio segment's context. - `response_format` string, nullable: Transcript format: 'json', 'text', 'srt', 'verbose_json', or 'vtt'. Provider support varies; forwarded as-is. - `timestamp_granularities` string[], nullable: Timestamp granularities to populate with 'verbose_json' (['word'] and/or ['segment']). - `temperature` number, nullable: Sampling temperature between 0 and 1. - `diarize` boolean, nullable: Label who speaks when. Not an OpenAI parameter; forwarded as-is. Mistral (Voxtral) models return a `speaker_id` per segment and require `timestamp_granularities=['segment']`; Deepgram models prefix the `text` with speaker labels. Other providers may reject it. - `user` string, nullable: End-user identifier for abuse tracking. - `file_id` string, nullable: Id of a file previously uploaded to Eden AI. - `file_url` string, nullable: An https URL or a base64 data URL pointing at the audio. ## Response `200` Successful Response - TranscriptionResponse: OpenAI-compatible transcription response, plus Eden ``cost`` / ``provider``. The provider's full transcript payload passes through — ``text`` plus any ``language``, ``duration``, ``words``, and ``segments`` the provider returns — alongside the Eden-added ``cost`` and ``provider`` fields. - `cost` number, nullable - `provider` string, nullable - `text` string, nullable - `usage` object, nullable --- [API](https://skmtc.dev/edenai/apis/eden-ai-api-v3.md) - [All operations](https://skmtc.dev/edenai/apis/eden-ai-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/edenai/apis/eden-ai-api-v3/revisions/20ddfd49a3f4?raw)