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

# Audio transcription

> Transcribe audio with multipart uploads and duration-based billing.

Transcribe an audio file through the attested TEE gateway using `multipart/form-data`. Responses
are buffered JSON with an `X-Receipt-Id` header for verification.

```bash theme={null}
POST https://api.redpill.ai/v1/audio/transcriptions
```

## Request body

**model** `string` *required*

Transcription model id, for example `openai/whisper-large-v3`; see the
[models catalog](https://docs.redpill.ai/api-reference/models.md) (`GET /v1/models`) for available ids.
Transcription models have `output_modalities: ["transcription"]` in the catalog.

**file** `file` *required*

Exactly one nonempty file, up to 25 MiB (26,214,400 bytes). The filename must include one of
these extensions: `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, or `webm`.
`qwen/qwen3-asr-1.7b` and `qwen/qwen3-asr-0.6b` accept up to 600 seconds of audio per
request and return `400 invalid_request_error` for longer files.

**language** `string`

Language code of 2–3 lowercase ASCII letters, for example `en`.
The Qwen3-ASR models detect the language themselves and may ignore this hint.

**prompt** `string`

Optional context for transcription, up to 4,096 Unicode characters.

**temperature** `number`

Sampling temperature from 0 through 1.

**response\_format** `string`

`json` (default) is supported by every model. `verbose_json` is supported only by
`openai/whisper-large-v3`; `mistralai/voxtral-small-24b-2507`, `qwen/qwen3-asr-1.7b` and
`qwen/qwen3-asr-0.6b` return `400 invalid_request_error` for `verbose_json`. Text, subtitle,
and other response formats are not supported.

**timestamp\_granularities\[]** `string[]`

`word` and/or `segment`, once each, only with `openai/whisper-large-v3` and
`response_format=verbose_json`. Repeat the field to request both. `timestamp_granularities`
is also accepted; do not mix spellings. Word-level timestamps are not returned; segments
may be absent.

**stream** `boolean`

Omit this field or send the literal form value `false`. Streaming is not supported;
`true` and all other values return `400`.

**user** `string`

Accepted for SDK compatibility but removed before forwarding upstream.

Duplicate scalar fields, malformed multipart, and invalid UTF-8 text return `400`. Other fields,
including `provider`, `chunking_strategy`, `include[]`, and speaker fields, return
`400 unknown_parameter`. ACI E2EE is not supported on this endpoint.

The upload must complete within 60 seconds, the file must be at most 25 MiB, and malformed or
oversized multipart metadata returns `400` or `413`.

## Verified-serving constraints

**X-ACI-Provider** `string`

A JSON object with the same routing constraints as the JSON `provider` field, for example
`{"aci_verified":true}`. The header is consumed by the gateway and never forwarded upstream.
A `provider` form field is not accepted.

`aci_verified: true` requires a verified upstream. `aci_session_ids` pins a nonempty list of
64-hex session ids and implies verified serving; combining pins with `aci_verified: false` is
invalid. Unavailable pins return `412 session_not_accepted`; failed required verification returns
`503 upstream_verification_failed`, before forwarding the audio. The header must appear once,
contain only ASCII bytes, and be at most 8,192 bytes. Malformed or non-object JSON, invalid pins,
and unknown `aci_` members return `400`. JSON endpoints reject this header.

Before uploading with constraints, obtain the attestation report over the accepted attested,
SPKI-pinned channel, accept its workload provenance, and confirm that
`service_capabilities.supported_multipart_constraint_endpoints` contains
`/v1/audio/transcriptions`. Refuse the upload locally if support is absent. Intersect caller
session pins with locally accepted sessions and refuse disjoint sets. Retain the effective policy
and check the receipt's cited session against it: receipt body hashes do not commit to this
header. TEE-only host requirements apply independently.

## Example

Let the client set the multipart `Content-Type` boundary. Name Node SDK files explicitly:
`toFile(buf)` uses `unknown_file`, which has no extension and returns `400`.

```bash cURL theme={null}
curl --fail-with-body --silent --show-error \
  https://api.redpill.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $REDPILL_AI_API_KEY" \
  -D audio-headers.txt \
  -F 'model=openai/whisper-large-v3' \
  -F 'file=@audio.wav' \
  -F 'response_format=json'
```

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

client = OpenAI(
    api_key=os.environ["REDPILL_AI_API_KEY"],
    base_url="https://api.redpill.ai/v1",
)

with open("audio.wav", "rb") as audio:
    response = client.audio.transcriptions.create(
        model="openai/whisper-large-v3",
        file=audio,
        response_format="json",
    )
print(response.text)
```

```javascript Node.js theme={null}
import { readFile } from 'node:fs/promises';
import OpenAI, { toFile } from 'openai';

const client = new OpenAI({
  apiKey: process.env.REDPILL_AI_API_KEY,
  baseURL: 'https://api.redpill.ai/v1',
});

const buf = await readFile('audio.wav');
const response = await client.audio.transcriptions.create({
  model: 'openai/whisper-large-v3',
  file: await toFile(buf, 'audio.wav'),
  response_format: 'json',
});
console.log(response.text);
```

```bash Private AI Proxy theme={null}
pap curl https://api.redpill.ai/v1/audio/transcriptions -- \
  --fail-with-body --silent --show-error \
  -H @auth-headers.txt \
  -F 'file=@audio.wav' \
  -F 'model=openai/whisper-large-v3' \
  -H 'X-ACI-Provider: {"aci_verified":true}'
```

To require verified serving with cURL, add `-H 'X-ACI-Provider: {"aci_verified":true}'` after
checking the capability above.

For Private AI Proxy, `auth-headers.txt` contains `Authorization: Bearer <key>`; restrict its
permissions to your user and remove it after use. `pap curl` verifies and pins the gateway channel;
it does not audit receipts. Use `pap serve` or ACI verifier SDK clients for receipt audits
([Verify a response](https://docs.redpill.ai/guides/verify-a-response.md)); the plain OpenAI SDK examples do not audit receipts.

## Response

The cost below is illustrative, not a model price.

```json theme={null}
{
  "text": "Hello, world.",
  "usage": { "type": "duration", "seconds": 3, "cost": 0.0003 }
}
```

`json` returns `text`, `usage`, and optional `languages: [{"code":"en"}]`. For
`openai/whisper-large-v3`, `verbose_json` also includes `duration` and `language`.
Word-level timestamps are not returned. With `verbose_json`, Whisper responses may include
`segments`; they can be absent.

`usage` contains `type: "duration"` and integer `seconds`. Audio pricing is USD per second of input
audio, billed per started second: `usage.seconds` is rounded up (`2.965` becomes `3`). Verbose
`duration` retains the raw value. The gateway adds `usage.cost` only when the deployment has audio
pricing, in USD: billable seconds times the applicable rate. Provider-reported cost is not echoed.
Without a valid duration, the transcript is withheld with `502` and no audio is billed.

Read `X-Receipt-Id` and fetch `GET /v1/aci/receipts/{id}` using the same bearer token. Audio receipts
have `chat_id: null`, so use the receipt id. See [Get receipt](https://docs.redpill.ai/api-reference/receipts.md) and
[Verify a response](https://docs.redpill.ai/guides/verify-a-response.md).

## Errors

Errors use a JSON `error` object, with `error.code` and `error.param` where applicable.

| Status | Error field | Condition |
| - | - | - |
| 400 | `code: unknown_parameter` | Unrecognized form field; `param` names the field. |
| 400 | `code: invalid_parameter` | Missing or invalid required fields, unsupported filename extension, response format other than `json` or `verbose_json`, invalid timestamp options, duplicate scalar fields, invalid UTF-8, malformed multipart, or exceeded multipart metadata limits. |
| 400 | `type: invalid_request_error`, `code: null`, `param: null` | `verbose_json` with `mistralai/voxtral-small-24b-2507`: `Currently do not support verbose_json for voxtral-small-24b`. |
| 400 | `type: invalid_request_error` | Invalid or duplicate `X-ACI-Provider` header, including malformed constraints. |
| 400 | `type: e2ee_unsupported_endpoint` | E2EE headers are present; the refusal is decided before parsing or admission. |
| 404 | `type: model_not_found` | No eligible route supports transcription for the requested model. |
| 408 | `code: upload_timeout` | Upload exceeds the 60-second deadline; the connection closes. |
| 413 | `code: request_too_large` | File or whole-body size limit exceeded; the connection closes. |
| 429 | `type: rate_limit_error`, `code: rate_limit_exceeded` | Capacity is full or a rate limit is reached; respect `Retry-After` when present. |
| 502 | `type: upstream_error` | Upstream failure, response over 8 MiB, missing string `text`, or invalid duration. Without a valid duration, the transcript is withheld and no audio is billed. |

Authentication, budget, and other routing constraint errors follow the shared
[error handling reference](https://docs.redpill.ai/guides/error-handling.md).

## Related

> [card] [Models](https://docs.redpill.ai/api-reference/models.md)
>
> Find available model ids and capabilities.

> [card] [Get receipt](https://docs.redpill.ai/api-reference/receipts.md)
>
> Retrieve the signed receipt using X-Receipt-Id.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.