---
title: "Transcribe a media file"
method: POST
path: "/transcriptions"
tags: ["Transcriptions"]
---

# Transcribe a media file

`POST /transcriptions`

## Request

- Base URL: `https://api.cut.pro/api/v1`
- URL: `https://api.cut.pro/api/v1/transcriptions`
- Auth: API key in header `X-Api-Key`

Starts a transcription for a media file you uploaded via `POST /transcriptions/upload`. Credits are charged per minute of audio, plus a surcharge when `speaker_labels` is requested. Check the balance at `GET /balance` first.

Responds `202` with `status: processing` when the ASR worker was dispatched: poll `GET /transcriptions/{transcriptionId}` until `status` is `ready` (or `failed` / `no_speech`), then fetch the text.

Responds `200` when nothing had to run. That happens when the same audio was already transcribed (the transcript is shared per media, so a re-run is a cache hit and `credits_charged` is `0`), or when the audio is silent, which comes back as `no_speech` and is not billed.

Passing a `media_id` that is already in your library re-runs it. That is how a transcript created without diarization is upgraded: ask again with `speaker_labels: true` and the audio is reprocessed, because the speaker column cannot be added after the fact.

## Request body

- object
  - `media_id` string, required: The `media_id` from `POST /transcriptions/upload`, or one already in your library.
  - `speaker_labels` boolean: Identify who is speaking on each cue. Costs more and forces a full re-run. Default `false`.
  - `source_language` string: Spoken language, e.g. `pt`. Omit to auto-detect, but pin it for short clips, where detection routinely mistakes Portuguese for Spanish.
  - `file_name` string: Original file name, used as the job title. Required for a media you just uploaded.
  - `file_size` number: Size in bytes. Required for a media you just uploaded.
  - `duration` number: Duration in seconds. Fallback only: the stored file is probed and its real duration wins.
  - `content_type` string: MIME type of the uploaded file.

## Response `200`

Response for status 200

- object
  - `id` string, required
  - `status` 'ready' | 'no_speech', required
  - `credits_charged` number, required

## Other responses

- `202`: Response for status 202
- `400`: Response for status 400
- `402`: Response for status 402
- `404`: Response for status 404
- `422`: Response for status 422

---

[API](https://skmtc.dev/cut/apis/cutpro-api.md) · [All operations](https://skmtc.dev/cut/apis/cutpro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cut/apis/cutpro-api/revisions/89d0bafe529c?raw)