> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inputapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcription and translation

> Upload audio, read text, and distinguish transcription from translation.

Transcription and translation upload audio files and return text, not synthesized speech.

| Goal | Endpoint | Result |
| - | - | - |
| Recognize the original language | [POST /v1/audio/transcriptions](/en/api-reference/audio-transcriptions) | Text in the original language |
| Translate into English | [POST /v1/audio/translations](/en/api-reference/audio-translations) | English text |

OpenAI-compatible translation means audio-to-English, not translation into an arbitrary target language. For another language, transcribe first and send the text to a translation-capable chat model. A transcription model may not support the translation endpoint.

## Upload a recording

Set `API_BASE_URL` (including `/v1`), `API_KEY`, and `API_MODEL` using the [Python SDK guide](/en/guides/python). Set `API_AUDIO_PATH` to a local recording. Save as `transcribe.py` and run `python transcribe.py transcribe`. After selecting a translation-capable model, run `python transcribe.py translate`.

Running this uploads the recording. The example accepts nonempty files up to 20 MiB, a client example limit rather than a universal model limit. Keep the correct filename extension and confirm codec support. The SDK manages the multipart boundary; `file` contains bytes, not a local-path string or remote URL.

```python theme={null}
import os
import sys
from pathlib import Path
from openai import OpenAI, APIConnectionError, APIStatusError

mode = sys.argv[1] if len(sys.argv) == 2 else ""
if mode not in ("transcribe", "translate"):
    raise SystemExit("Usage: python transcribe.py transcribe|translate")
source = Path(os.environ["API_AUDIO_PATH"])
# A local example limit, not a universal provider upload limit.
if not 0 < source.stat().st_size <= 20 * 1024 * 1024:
    raise SystemExit("Choose a nonempty recording up to 20 MiB for this example.")

with OpenAI(base_url=os.environ["API_BASE_URL"].rstrip("/"),
            api_key=os.environ["API_KEY"], timeout=120.0, max_retries=0) as client:
    try:
        endpoint = client.audio.transcriptions if mode == "transcribe" else client.audio.translations
        with source.open("rb") as recording:
            result = endpoint.create(model=os.environ["API_MODEL"], file=recording, response_format="json")
        if not isinstance(result.text, str):
            raise ValueError("Expected a text field.")
        print(result.text)
    except APIStatusError as error:
        raise SystemExit(f"Request failed (HTTP {error.status_code}). Check the request logs.")
    except APIConnectionError:
        raise SystemExit("Connection failed. Check the API address and network.")
    except ValueError:
        raise SystemExit("Invalid transcription response; expected JSON with text.")
```

## Response formats and long recordings

This example uses `response_format: json` and reads `text`. Silence may produce an empty string; let the application decide whether to accept it. `text`, `srt`, and `vtt` produce text responses, not JSON objects with a `text` field. For timestamps, confirm support for `verbose_json` and `timestamp_granularities[]`. Timestamps and speaker diarization are not universal capabilities.

`language` hints at the transcription input language; it does not select the translation target. `prompt` provides context. Split long recordings to fit service limits, preserve time offsets, and handle overlapping text. Reverse proxies, gateways, and channels can impose smaller upload limits than the model.

This page uses non-SSE responses for recorded files. Streaming transcription, speaker events, and realtime audio protocols require separate channel verification; do not parse them as Chat Completions events.

Reference: [OpenAI file transcription and translation](https://developers.openai.com/api/docs/guides/speech-to-text).

[简体中文](/zh/guides/speech-to-text)

[Related guide: Audio conversation input](/en/guides/audio-input)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.