> ## 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 Transcription

> Transcribes audio into the input language

<Note>
  For coding agents, discover the current recommended STT shortlist first with `GET /v1/models?recommended_for=stt`, then send the selected `model` explicitly to this endpoint.
</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>
  Audio file to transcribe. Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm.
</ParamField>

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

<ParamField body="language" type="string">
  Language of the audio in ISO-639-1 format (e.g., `en`, `zh`, `ja`).
</ParamField>

<ParamField body="prompt" type="string">
  Optional text to guide the model's style or continue a previous segment.
</ParamField>

<ParamField body="response_format" type="string" default="json">
  Output format: `json`, `text`, `srt`, `verbose_json`, `vtt`.
</ParamField>

<ParamField body="temperature" type="number" default="0">
  Sampling temperature (0 to 1).
</ParamField>

<ParamField body="timestamp_granularities" type="array">
  Timestamp granularity: `word` and/or `segment`. Requires `verbose_json`.
</ParamField>

## Response

<ResponseField name="text" type="string">
  The transcribed text.
</ResponseField>

For `verbose_json`:

<ResponseField name="task" type="string">
  Always `transcribe`.
</ResponseField>

<ResponseField name="language" type="string">
  Detected language.
</ResponseField>

<ResponseField name="duration" type="number">
  Audio duration in seconds.
</ResponseField>

<ResponseField name="segments" type="array">
  Transcription segments with timestamps.
</ResponseField>

<ResponseField name="words" type="array">
  Word-level timestamps (if requested).
</ResponseField>

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

  ```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("audio.mp3", "rb") as audio_file:
      response = client.audio.transcriptions.create(
          model="whisper-1",
          file=audio_file,
          language="en"
      )

  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.transcriptions.create({
    model: 'whisper-1',
    file: fs.createReadStream('audio.mp3'),
    language: 'en'
  });

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

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

  $file = new CURLFile('audio.mp3', 'audio/mpeg', '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',
          'language' => 'en'
      ]
  ]);

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

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

<ResponseExample>
  ```json Response (json) theme={null}
  {
    "text": "Hello, this is a test of the transcription API."
  }
  ```

  ```json Response (verbose_json) theme={null}
  {
    "task": "transcribe",
    "language": "english",
    "duration": 5.5,
    "text": "Hello, this is a test of the transcription API.",
    "segments": [
      {
        "id": 0,
        "start": 0.0,
        "end": 2.5,
        "text": "Hello, this is a test",
        "tokens": [...]
      }
    ]
  }
  ```
</ResponseExample>

## Translation

To translate audio to English, use the translations endpoint:

```python theme={null}
response = client.audio.translations.create(
    model="whisper-1",
    file=audio_file
)
```