POST /v1/audio/transcriptions

Send an audio file using multipart/form-data and retrieve its transcript with ClovisSTT/transcription.

https://llm-gateway.clovis-ai.fr/v1/audio/transcriptions

Authenticate each request with Authorization: Bearer <CLOVIS_API_KEY>. Keep the API key on your server.

Parameters

Field	Type	Value	Description
file	Binary file	Audio file contents	Required. Open the file in rb mode with the SDK or use -F 'file=@audio.mp3' with cURL.
model	String	ClovisSTT/transcription	Required. Use this public name for request routing.
response_format	String	json	Set explicitly. Returns an object containing text and usage.
language	String	ar, nl, en, fr, de, hi, it, pt, es	Optional. Codes listed by the HTTP validator. Requests with fr and en passed the integration test. Requests also work without this field.

language describes the input recording. In the test with language="en", the French sample is still transcribed in French.

The nine codes listed by the HTTP validator are distinct from the 13 Voxtral model languages. The integration test used a French sample; it does not measure transcription quality across languages.

Parameters are multipart body fields. Let the SDK or cURL generate the Content-Type and boundary.

Response formats

response_format	Staging behavior
json	HTTP 200. JSON object containing the transcript and audio duration directly. Used in the examples below.
text	HTTP 200. Nested JSON with Content-Type: application/json. See below.
verbose_json	HTTP 400. Rejected for this model.
diarized_json	HTTP 400. Rejected for this model.
srt, vtt	HTTP 400. Rejected by this route.
Field omitted	HTTP 400. Processing selects verbose_json, which this model rejects.

json response

{"text":" Oui, c'est vrai.","usage":{"type":"duration","seconds":5.0}}

• text contains the transcript. Use .strip() to remove leading and trailing whitespace.
• usage.type is duration in this response.
• usage.seconds contains the duration recorded by the service. The 4.48 s sample produces a value of 5 s.

text response

{"text":"{\"text\":\" Oui, c'est vrai.\",\"usage\":{\"type\":\"duration\",\"seconds\":5}}","usage":null}

The SDK returns this body as a string. To access the transcript without decoding two JSON wrappers, use response_format="json" and read transcript.text.

Python example

python -m pip install 'openai==3.35.1'
export CLOVIS_API_KEY='your-staging-api-key'

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["CLOVIS_API_KEY"],
    base_url="https://llm-gateway.clovis-ai.fr/v1",
    timeout=120.0,
    max_retries=0,
) as client:
    with open("audio.mp3", "rb") as audio_file:
        transcript = client.audio.transcriptions.create(
            model="ClovisSTT/transcription",
            file=audio_file,
            response_format="json",
            language="fr",
        )
    print(transcript.text.strip())

Remove language="fr" to submit the file without specifying its language.

cURL example

curl --fail-with-body --max-time 120 \
  https://llm-gateway.clovis-ai.fr/v1/audio/transcriptions \
  -H "Authorization: Bearer $CLOVIS_API_KEY" \
  -F 'file=@audio.mp3' \
  -F 'model=ClovisSTT/transcription' \
  -F 'response_format=json'

Add -F 'language=fr' to specify French.

Python client settings

Setting	Example value	Effect
api_key	os.environ["CLOVIS_API_KEY"]	Adds Bearer authentication.
base_url	https://llm-gateway.clovis-ai.fr/v1	API root. The SDK appends /audio/transcriptions.
timeout	120.0	Configures client network timeouts in seconds. A timeout raises APITimeoutError.
max_retries	0	Disables automatic retries, including after HTTP 500.

These configure the client, not the multipart body. To override a single request, use client.with_options(timeout=120.0, max_retries=0) before .audio.transcriptions.create(...).

Audio formats

The MP3 format was tested with a 69,990-byte, 4.48 s recording.

Send the complete file. The MP3 example works without PCM conversion or Base64 encoding.

Errors

Request	Result
Missing authentication header	HTTP 401
Missing file	HTTP 422
Missing model	HTTP 400
Backend name voxtral-mini-4b-realtime with the test key	HTTP 403
Language code xx	HTTP 400, listing the nine accepted codes
Unrecognized response format	HTTP 400

Validation scope

Verified on 19 October 2026 on staging using a 4.48 s French recording. SDK examples use openai 3.35.1. HTTP transport was tested on staging; JSON SDK and cURL examples were verified locally using the recorded real response. Client timeout and retry tests use a controlled local transport. Parameters without an established effect are excluded from this reference.