---
title: "Transcribe (one request)"
method: POST
path: "/v1/transcribe"
tags: ["Transcripts"]
---

# Transcribe (one request)

`POST /v1/transcribe`

## Request

- Base URL: `https://api.aircaps.com`
- URL: `https://api.aircaps.com/v1/transcribe`
- Auth: HTTP bearer

Send the audio and get the finished transcript back in one request: the upload, [Create a transcript](/api-reference/create-transcript) and the wait in one call. The body is the raw audio (any audio or video format) with the options as query parameters, or a `multipart/form-data` form whose `file` field is the audio and whose other fields are the options. Options are those of Create a transcript except `audio_url` and `file_id`; `keyterms` may repeat, `metadata` and `speaker_identification` are JSON. If the transcript is not finished within `wait`, the answer is `202` with the transcript so far: fetch it with [Get a transcript](/api-reference/get-transcript), optionally with `wait`.

## Query parameters

- `model` string, required
- `language_code` string
- `wait` number

## Headers

- `Idempotency-Key` string

## Request body `multipart/form-data`

- object
  - `file` string, binary, required
  - `model` string
  - `language_code` string

## Response `200`

The finished transcript (as Get a transcript).

- Transcript
  - `id` string, required: Transcript ID.
  - `object` 'transcript', required
  - `status` 'queued' | 'processing' | 'completed' | 'error', required: `queued`: waiting for a processing slot. `processing`: being transcribed. `completed`: result fields present. `error`: see `error`.
  - `created_at` string, date-time, required: When the transcript was created (UTC).
  - `started_at` string, date-time, nullable, required: When processing started.
  - `completed_at` string, date-time, nullable, required: When the job finished (completed or error).
  - `audio_url` string, nullable, required: The submitted `audio_url`, if any.
  - `file_id` string, nullable, required: The submitted `file_id`, if any.
  - `language_code` 'en', required: Language of the transcript (normalised).
  - `model` 'a5s-async-v1', required
  - `audio_duration` number, nullable, required: Audio duration in seconds, once known.
  - `metadata` object, nullable, required: Your `metadata`, echoed back.
  - `webhook_url` string, nullable, required: Webhook target, if any.
  - `webhook_status` 'pending' | 'delivered' | 'failed' | 'null', nullable, required: Webhook delivery state, if `webhook_url` was set.
  - `webhook_status_code` integer, nullable, required: HTTP status of the last webhook delivery.
  - `error` JobError, required
    - `code` 'invalid_audio' | 'audio_too_long' | 'file_too_large' | 'download_failed' | 'file_not_found' | 'usage_limit_reached' | 'internal_error' | 'canceled', required: Why the job failed. Failed jobs never count toward usage.
    - `message` string, required: Human-readable detail.
  - `text` string: Completed only. Full transcript: verbatim, lowercase, no punctuation.
  - `speakers` TranscriptSpeaker[]: Completed only. With `speaker_identification`, each speaker also has `speaker_id`, `name`, `score`, `matches` and `compared_duration`.
    - `id` string, required
    - `speaking_time` number, required: Seconds this speaker talks.
    - `speaker_id` string, nullable: Only with `speaker_identification`: the enrolled speaker matched with this speaker (its best score reached `threshold`), or `null`. Two speakers can match the same enrolled speaker when one person was split in two.
    - `name` string, nullable: Only with `speaker_identification`: the matched enrolled speaker's name.
    - `score` number, nullable: Only with `speaker_identification`: the matched enrolled speaker's score, or `null`.
    - `matches` SpeakerMatch[]: Only with `speaker_identification`: the 3 best-scoring enrolled speakers, best first, whether or not they reached `threshold`. Empty when the speaker had too little speech to compare.
      - `speaker_id` string, required: Enrolled speaker ID.
      - `name` string, nullable, required: The enrolled speaker's name.
      - `score` number, required: Similarity of this speaker's voice to the enrolled speaker (-1 to 1).
    - `compared_duration` number: Only with `speaker_identification`: seconds of this speaker's audio that were compared.
  - `utterances` Utterance[]: Completed only. Speaker turns, in time order; overlapping speech overlaps.
    - `speaker` string, required: Speaker label (`speaker_0`, `speaker_1`, … in order of first speech).
    - `speaker_name` string, nullable: Only with `speaker_identification`: the name of the enrolled speaker this speaker was matched with, or `null`.
    - `start` number, required: Start time in seconds.
    - `end` number, required: End time in seconds.
    - `text` string, required: Text of the utterance.
    - `words` Word[], required: Words of the utterance.
      - `text` string, required: The word.
      - `start` number, required: Start time in seconds.
      - `end` number, required: End time in seconds.
      - `speaker` string, required: Speaker label.
  - `words` Word[]: Completed only. Every word, in time order.
    - `text` string, required: The word.
    - `start` number, required: Start time in seconds.
    - `end` number, required: End time in seconds.
    - `speaker` string, required: Speaker label.
  - `timing_mode` 'phrase' | 'region': The `timing_mode` used.
  - `keyterms` string[]: Only when the transcript was created with `keyterms`: the list used (duplicates removed).
  - `large_meeting` boolean: Only when the transcript was created with `large_meeting: true`.
  - `speaker_identification` TranscriptSpeakerIdentification
    - `model` 'aircaps-speaker-id-v1', required
    - `status` 'pending' | 'completed' | 'failed' | 'skipped', required: `pending`: the transcript is not finished. `completed`: matched (possibly nobody). `failed`: speaker identification was unavailable; the transcript is complete without names (see `error`). `skipped`: the transcript failed.
    - `threshold` number, required
    - `speaker_ids` string[], nullable, required: The requested `speaker_ids`, or `null` for every enrolled speaker.
    - `speakers_compared` integer, nullable, required: Enrolled speakers compared (those that existed and had enrollments when the transcript was processed).
    - `speakers_identified` integer, nullable, required: Transcript speakers that got a name.
    - `error` object, nullable, required
      - `code` 'speaker_identification_failed'
      - `message` string

## Other responses

- `202`: Not finished within `wait`: the transcript so far.
- `400`: Invalid request. Codes: `invalid_request`, `unsupported_language`, `unsupported_model`.
- `401`: Missing or invalid API key. Codes: `unauthorized`.
- `403`: The account may not do this. Codes: `account_suspended`, `account_disabled`, `usage_limit_reached`, `model_access_denied`.
- `409`: Idempotency key reused with a different body. Codes: `idempotency_conflict`.
- `413`: Larger than 1 GB. Codes: `file_too_large`.
- `429`: Rate or queue limit reached. Codes: `rate_limited`, `queue_full`.
- `500`: Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.
- `503`: Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.

---

[API](https://skmtc.dev/aircaps/apis/aircaps-api.md) - [All operations](https://skmtc.dev/aircaps/apis/aircaps-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aircaps/apis/aircaps-api/revisions/442d566f9827?raw)