---
title: "Create audio transcription request"
method: POST
path: "/v1/audio/transcriptions"
tags: ["Audio"]
---

# Create audio transcription request

`POST /v1/audio/transcriptions`

## Request

- Base URL: `https://api.together.ai`
- URL: `https://api.together.ai/v1/audio/transcriptions`
- Auth: HTTP bearer

Transcribes audio into text

## Request body `multipart/form-data`

- AudioTranscriptionRequest
  - `file` union, required: Audio file upload or public HTTP/HTTPS URL. Supported formats: .wav, .mp3, .m4a, .webm, .flac, .ogg, .opus, .aac. Maximum duration 4 hours; longer audio is rejected with `audio_too_long`. Binary uploads are additionally capped at 80 MB (HTTP 413); URL-fetched audio is capped at 1 GB.
    - string, binary: Audio file uploaded as binary. Maximum upload size 80 MB (requests above this are rejected with HTTP 413). For larger payloads, host the file and submit a URL instead.
    - string, uri: Public HTTPS URL the server fetches the audio from. Server-side fetch limit is 1 GB; downloads exceeding the cap fail with `file_too_large`.
  - `model` 'openai/whisper-large-v3': Model to use for transcription
  - `language` string: Optional ISO 639-1 language code. If `auto` is provided, language is auto-detected.
  - `prompt` string: Optional text to bias decoding. Supported only on Whisper-family models (e.g. `openai/whisper-large-v3`). Other STT models (e.g. `nvidia/parakeet-tdt-0.6b-v3`) accept the field for API compatibility but ignore it.
  - `response_format` 'json' | 'verbose_json': The format of the response
  - `temperature` number: Sampling temperature between 0.0 and 1.0
  - `timestamp_granularities` union: Controls level of timestamp detail in verbose_json. Only used when response_format is verbose_json. Can be a single granularity or an array to get multiple levels.
    - 'segment' | 'word'
    - string[]
  - `diarize` boolean: Whether to enable speaker diarization. When enabled, you will get the speaker id for each word in the transcription. In the response, in the words array, you will get the speaker id for each word. In addition, we also return the speaker_segments array which contains the speaker id for each speaker segment along with the start and end time of the segment along with all the words in the segment. <br> <br> For eg - ... "speaker_segments": [ "speaker_id": "SPEAKER_00", "start": 0, "end": 30.02, "words": [ { "id": 0, "word": "Tijana", "start": 0, "end": 11.475, "speaker_id": "SPEAKER_00" }, ...
  - `min_speakers` integer: Minimum number of speakers expected in the audio. Used to improve diarization accuracy when the approximate number of speakers is known.
  - `max_speakers` integer: Maximum number of speakers expected in the audio. Used to improve diarization accuracy when the approximate number of speakers is known.

## Response `200`

OK

- union
  - AudioTranscriptionJsonResponse
    - `text` string, required: The transcribed text
  - AudioTranscriptionVerboseJsonResponse
    - `language` string, required: The language of the audio
    - `duration` number, required: The duration of the audio in seconds
    - `text` string, required: The transcribed text
    - `segments` AudioTranscriptionSegment[], required: Array of transcription segments
      - `id` integer, required: Unique identifier for the segment
      - `start` number, required: Start time of the segment in seconds
      - `end` number, required: End time of the segment in seconds
      - `text` string, required: The text content of the segment
    - `words` AudioTranscriptionWord[]: Array of transcription words (only when timestamp_granularities includes 'word')
      - `word` string, required: The word
      - `start` number, required: Start time of the word in seconds
      - `end` number, required: End time of the word in seconds
      - `speaker_id` string: The speaker id for the word (only when diarize is enabled)
    - `speaker_segments` AudioTranscriptionSpeakerSegment[]: Array of transcription speaker segments (only when diarize is enabled)
      - `speaker_id` string, required: The speaker identifier
      - `start` number, required: Start time of the speaker segment in seconds
      - `end` number, required: End time of the speaker segment in seconds
      - `words` AudioTranscriptionWord[], required: Array of words spoken by this speaker in this segment
        - `word` string, required: The word
        - `start` number, required: Start time of the word in seconds
        - `end` number, required: End time of the word in seconds
        - `speaker_id` string: The speaker id for the word (only when diarize is enabled)
      - `text` string, required: The full text spoken by this speaker in this segment
      - `id` integer, required: Unique identifier for the speaker segment

## Other responses

- `400`: BadRequest. Possible error codes include `audio_too_long` (audio duration exceeds the 4 hour cap), `file_too_large` (URL-fetched audio exceeds the 1 GB server-side cap), `unsupported_format` (codec or container could not be decoded), and `invalid_params` (request parameters failed validation).
- `401`: Unauthorized
- `413`: Payload Too Large. The request body exceeded the 80 MB direct-upload limit. For larger payloads, host the file and submit an HTTPS URL via the `file` field (URL-fetched audio is capped at 1 GB server-side).
- `429`: RateLimit

## Changes

- **2026-10-22** `bb5257b3173a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/together/apis/together-apis/changes/v1/audio/transcriptions/post.md)

---

[API](https://skmtc.dev/together/apis/together-apis.md) - [All operations](https://skmtc.dev/together/apis/together-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/together/apis/together-apis/revisions/93438ddac711?raw)