# Transcribe audio to text

`POST /v1/audio/transcriptions`

Transcribes audio to text using speech-to-text models. Accepts audio files via multipart form upload. Available models: openai/whisper-large-v3, openai/whisper-large-v3-turbo

## Authentication

Send `Authorization: Bearer $KOSCOMPUTE_API_KEY`.

## Request

Content type: `multipart/form-data`

| Field | Type | Required | Description |
|---|---|---:|---|
| `file` | string (binary) | Yes | Audio file (multipart) |
| `model` | string | Yes | See the endpoint guide for behavior and model support. |
| `language` | string | No | See the endpoint guide for behavior and model support. |
| `response_format` | string | No | Values: `json`, `text`, `srt`, `verbose_json`, `vtt`. |
| `temperature` | number | No | See the endpoint guide for behavior and model support. |
| `timestamp_granularities` | array | No | See the endpoint guide for behavior and model support. |

## Examples

### cURL

```bash
curl https://api.koscompute.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $KOSCOMPUTE_API_KEY" \
  -F "file=@sample.wav" \
  -F "model=openai/whisper-large-v3-turbo"
```

### Python

```python
import os
import requests

with open("sample.wav", "rb") as audio:
    response = requests.post(
        "https://api.koscompute.com/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {os.environ['KOSCOMPUTE_API_KEY']}"},
        files={"file": ("sample.wav", audio, "audio/wav")},
        data={"model": "openai/whisper-large-v3-turbo"},
    )
```

### JavaScript

```javascript
const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("model", "openai/whisper-large-v3-turbo");
const response = await fetch("https://api.koscompute.com/v1/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.KOSCOMPUTE_API_KEY}` },
  body: form,
});
```

## Responses

| Status | Meaning |
|---:|---|
| `200` | Transcription result |
| `400` | Bad request — invalid parameters or payload |
| `401` | Invalid or missing API key |
| `403` | Model not allowed for this API key |
| `404` | Public model not found |
| `413` | Request body exceeds the limit |
| `429` | Rate limit or admission capacity is full. The message states when to retry; vision saturation also reports active/total vision concurrency. |
| `502` | Invalid or failed upstream response |
| `503` | No healthy route |
| `504` | Backend generation timeout |
| `500` | Internal server error |

## Next steps

Use the endpoint guide for complete workflows, model capability notes, streaming behavior, and retry advice.