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

# Create Translation

> Translates audio into English text

## Overview

Translates audio in any supported language into English text. Unlike transcription, this endpoint always outputs English text regardless of the input language.

<Note>
  This page documents **audio translation** (`POST /v1/audio/translations`). For **text translation**, use `POST /v1/translations`.
</Note>

<Note>
  Do not use `recommended_for=translation` for this endpoint. That recommendation scene is reserved for text translation models on `POST /v1/translations`.
</Note>

## Request Body

**Synchronous request timeout:** This non-chat endpoint waits for the routed model to finish. Large inputs, long audio, or large batches can exceed common 30s client defaults, so set your HTTP client timeout to at least `120s`.

<ParamField body="file" type="file" required>
  The audio file to translate. Supported formats: `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. Maximum file size is 25 MB.
</ParamField>

<ParamField body="model" type="string" default="whisper-1">
  The model to use. Currently only `whisper-1` is supported.
</ParamField>

<ParamField body="prompt" type="string">
  An optional text to guide the model's style or continue a previous segment. Should be in English.
</ParamField>

<ParamField body="response_format" type="string" default="json">
  The format of the output. Options: `json`, `text`, `srt`, `verbose_json`, `vtt`.
</ParamField>

<ParamField body="temperature" type="number">
  The sampling temperature, between 0 and 1. Higher values like 0.8 produce more random output, while lower values like 0.2 make output more focused and deterministic.
</ParamField>

## Response

<ResponseField name="text" type="string">
  The translated text in English.
</ResponseField>

For `verbose_json` format, the response also includes:

<ResponseField name="language" type="string">
  The detected language of the input audio.
</ResponseField>

<ResponseField name="duration" type="number">
  The duration of the input audio in seconds.
</ResponseField>

<ResponseField name="segments" type="array">
  Segments of the translated text with timestamps.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/audio/translations" \
    -H "Authorization: Bearer sk-your-api-key" \
    -F "file=@german_audio.mp3" \
    -F "model=whisper-1"
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

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

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';
  import fs from 'fs';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.audio.translations.create({
    model: 'whisper-1',
    file: fs.createReadStream('german_audio.mp3')
  });

  console.log(response.text);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/audio/translations');

  $file = new CURLFile('german_audio.mp3', 'audio/mpeg', 'german_audio.mp3');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => [
          'file' => $file,
          'model' => 'whisper-1'
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  echo $data['text'];
  ```
</RequestExample>

<ResponseExample>
  ```json json theme={null}
  {
    "text": "Hello, my name is Wolfgang and I come from Germany. Where are you from?"
  }
  ```

  ```json verbose_json theme={null}
  {
    "task": "translate",
    "language": "german",
    "duration": 8.470000267028809,
    "text": "Hello, my name is Wolfgang and I come from Germany. Where are you from?",
    "segments": [
      {
        "id": 0,
        "seek": 0,
        "start": 0.0,
        "end": 4.0,
        "text": " Hello, my name is Wolfgang and I come from Germany.",
        "tokens": [50364, 2425, 11, 452, 1315, 307, 25329, 293, 286, 808, 490, 5765, 13, 50564],
        "temperature": 0.0,
        "avg_logprob": -0.45,
        "compression_ratio": 1.0,
        "no_speech_prob": 0.0
      }
    ]
  }
  ```
</ResponseExample>

## Translation vs Transcription

| Feature            | Translation                      | Transcription              |
| ------------------ | -------------------------------- | -------------------------- |
| Output language    | Always English                   | Same as input              |
| Use case           | Convert foreign audio to English | Preserve original language |
| Language parameter | Not applicable                   | Optional hint              |

<Note>
  The translation endpoint automatically detects the source language and translates to English. The `language` parameter from transcription is ignored.
</Note>