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

# Audio transcriptions

> POST /v1/audio/transcriptions, OpenAI-compatible speech to text for a model deployed in your workspace.

```http theme={"dark"}
POST https://api.runinfra.ai/v1/audio/transcriptions
```

This operation is OpenAI-compatible and answers for a speech-to-text model you have deployed in your workspace. Send a multipart request with an audio `file` and that model's id. Audio up to 4 MB uploads directly in the request; larger files go through the [large-file lane](#large-files) below.

<RequestExample>
  ```python Python theme={"dark"}
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.runinfra.ai/v1",
      api_key=os.environ["RUNINFRA_GATEWAY_KEY"],
  )
  with open("meeting.mp3", "rb") as audio:
      transcript = client.audio.transcriptions.create(
          model=os.environ["MODEL_ID"],
          file=audio,
      )
  print(transcript.text)
  ```

  ```typescript TypeScript theme={"dark"}
  import fs from "node:fs";
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.runinfra.ai/v1",
    apiKey: process.env.RUNINFRA_GATEWAY_KEY,
  });
  const transcript = await client.audio.transcriptions.create({
    model: process.env.MODEL_ID,
    file: fs.createReadStream("meeting.mp3"),
  });
  console.log(transcript.text);
  ```

  ```bash cURL theme={"dark"}
  curl https://api.runinfra.ai/v1/audio/transcriptions \
    -H "Authorization: Bearer $RUNINFRA_GATEWAY_KEY" \
    -F model="$MODEL_ID" \
    -F file="@meeting.mp3"
  ```
</RequestExample>

## Request fields

| Field             | Meaning                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `file`            | The audio bytes, as a multipart file part. Direct uploads up to 4 MB.                                           |
| `model`           | The id of a speech-to-text model deployed in your workspace. `GET /v1/models` lists the ids your key can reach. |
| `response_format` | `json`, `text`, `verbose_json`, `srt`, or `vtt`.                                                                |
| `language`        | Advisory. The model identifies the spoken language automatically across 25 languages, so you can omit it.       |
| `upload_id`       | Replaces `file` for audio uploaded through the large-file lane.                                                 |

## Large files

Audio above 4 MB, up to 1 GB or 2 hours, uploads in its own step before transcription. Mint a one-shot upload URL, `PUT` the bytes to it, then transcribe with `upload_id` in place of `file`.

```bash theme={"dark"}
# 1. Mint a one-shot upload URL
curl https://api.runinfra.ai/v1/audio/uploads \
  -X POST \
  -H "Authorization: Bearer $RUNINFRA_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$MODEL_ID\"}"
# => { "id": "...", "upload_url": "..." }

# 2. PUT the audio bytes to the upload URL
curl -X PUT --upload-file interview.mp3 "$UPLOAD_URL"

# 3. Transcribe by upload_id instead of file
curl https://api.runinfra.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $RUNINFRA_GATEWAY_KEY" \
  -F model="$MODEL_ID" \
  -F upload_id="$UPLOAD_ID"
```

The upload URL is one-shot: one `PUT`, then it is spent.

## Limits

| Limit                         | Value                                        |
| ----------------------------- | -------------------------------------------- |
| Direct upload (`file`)        | Up to 4 MB                                   |
| Large-file lane (`upload_id`) | Up to 1 GB or 2 hours of audio               |
| Response formats              | `json`, `text`, `verbose_json`, `srt`, `vtt` |

## Billing

Transcription bills on the terms of the deployment serving it. The `POST /v1/audio/uploads` mint call and the `PUT` upload are free; only the transcription itself is billed.

## Errors

Failures use the same [OpenAI-style error envelope](/docs/api-reference/errors) as every other `/v1` operation. Two codes are specific to this endpoint.

| `error.code`       | Meaning                                                             |
| ------------------ | ------------------------------------------------------------------- |
| `upload_not_found` | The `upload_id` does not name a completed upload in this workspace. |
| `invalid_audio`    | The file or upload could not be decoded as audio.                   |

## Related

<Columns cols={3}>
  <Card title="Models" icon="list" href="/docs/api-reference/models">
    Discover available model ids and their published limits.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api-reference/authentication">
    Create the workspace key used by this request.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/docs/api-reference/errors">
    Handle validation, availability, and rate-limit failures.
  </Card>
</Columns>