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

# Create a transcription

> Transcribe audio into text with the OpenAI-compatible Yelu Audio Transcriptions API.

Transcribes an uploaded audio file. This endpoint uses `multipart/form-data`, not JSON.

## Endpoint

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.yelu.ai/v1/audio/transcriptions
```

## Headers

<ParamField header="Authorization" type="string" required>
  API key using the format `Bearer $YELU_API_KEY`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `multipart/form-data` with a generated boundary. Let curl, Fetch, or your HTTP library set this header; do not write the boundary manually.
</ParamField>

## Request body

<ParamField body="file" type="file" required>
  Audio file to transcribe. Accepted formats and maximum size depend on the selected model and deployment limits.
</ParamField>

<ParamField body="model" type="string" required>
  An audio-transcription model ID available to your account, such as `whisper-1` when enabled.
</ParamField>

<ParamField body="language" type="string">
  ISO 639-1 language code such as `en`. Supplying the correct language can improve latency and accuracy.
</ParamField>

<ParamField body="prompt" type="string">
  Optional context that guides spelling, terminology, or continuation. Do not use it as a security control.
</ParamField>

<ParamField body="response_format" type="string" default="json">
  `json`, `text`, `srt`, `verbose_json`, or `vtt`, subject to model support.
</ParamField>

<ParamField body="temperature" type="number" default="0">
  Sampling temperature supported by the transcription model.
</ParamField>

<ParamField body="timestamp_granularities[]" type="string[]">
  `word` or `segment` timestamps for compatible models and verbose responses.
</ParamField>

## Response

For `response_format=json`, the response contains the transcript:

<ResponseField name="text" type="string" required>
  Transcribed text.
</ResponseField>

Verbose formats can include language, duration, words, or segments. Text, SRT, and VTT formats return non-JSON bodies.

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/audio/transcriptions \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -F "file=@meeting.m4a" \
    -F "model=whisper-1" \
    -F "language=en" \
    -F "response_format=json"
  ```

  ```javascript JavaScript (Fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { openAsBlob } from 'node:fs';

  const form = new FormData();
  form.append('file', await openAsBlob('meeting.m4a'), 'meeting.m4a');
  form.append('model', 'whisper-1');
  form.append('language', 'en');
  form.append('response_format', 'json');

  const response = await fetch('https://api.yelu.ai/v1/audio/transcriptions', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}` },
    body: form,
  });
  if (!response.ok) throw new Error(await response.text());
  console.log((await response.json()).text);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  with open("meeting.m4a", "rb") as audio:
      response = requests.post(
          "https://api.yelu.ai/v1/audio/transcriptions",
          headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
          files={"file": ("meeting.m4a", audio, "audio/mp4")},
          data={"model": "whisper-1", "language": "en", "response_format": "json"},
          timeout=300,
      )
  response.raise_for_status()
  print(response.json()["text"])
  ```
</RequestExample>

<Tip>
  `openAsBlob` is available in Node.js 20 and later. Do not set `Content-Type` manually for multipart requests; Fetch adds the required boundary.
</Tip>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "text": "Today we reviewed the gateway migration and agreed to test streaming before rollout."
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "message": "An audio file is required.",
      "type": "invalid_request_error",
      "param": "file",
      "code": "missing_required_parameter"
    }
  }
  ```
</ResponseExample>

## Error codes

| Status      | Code or type             | Meaning                                                    |
| ----------- | ------------------------ | ---------------------------------------------------------- |
| `400`       | `invalid_request_error`  | Missing file/model, invalid format, or unsupported option. |
| `401`       | `authentication_error`   | Missing or invalid API key.                                |
| `403`       | `permission_denied`      | Transcription or the model is not enabled.                 |
| `404`       | `model_not_found`        | Model ID is unavailable.                                   |
| `413`       | `request_too_large`      | The audio upload exceeds the accepted size.                |
| `415`       | `unsupported_media_type` | File type or multipart encoding is unsupported.            |
| `429`       | `rate_limit_error`       | Request limit reached.                                     |
| `500`–`504` | `server_error`           | Temporary gateway or provider transcription failure.       |