---
title: "Transcribe an audio file you own (async)"
method: POST
path: "/v1/audio/transcribe"
tags: ["Audio"]
---

# Transcribe an audio file you own (async)

`POST /v1/audio/transcribe`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/audio/transcribe`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Starts an asynchronous transcription of audio (or a video's sound track) already
stored in your library. Upload it first with POST /v1/uploads (up to 2 GB) or
POST /v1/files/upload (up to 48 MB) and pass the `file_uuid` it returns.

**TWO DIFFERENT SCOPES ARE INVOLVED, and this is deliberate (D-15-07).**
Submitting needs `audio:write`. READING THE RESULT NEEDS `text:read`, because a
transcript is text: both GET /v1/transcriptions/{uuid} and GET /v1/jobs/{id}
classify this work into the `text` container.

**A token holding only `audio:write` can start this job, be charged for it, and then
never be able to read the transcript** - the status poll and the transcript read both
answer 404. Mint a token holding `audio:write` AND `text:read` for a complete
workflow. The 202 body repeats this warning.

## Request body

- object
  - `file_uuid` string, uuid, required: An audio or video file you own.
  - `language` string: Optional language hint, e.g. "de" or "en-US", or "auto" to detect it.
  - `diarize` boolean: Speaker separation. Must be a real boolean. Default false.
  - `refinement_type` 'raw' | 'refined' | 'summary' | 'conclusions' | 'devils_advocate' | 'action_points': What to produce beyond the raw transcript.
  - `source_file_uuid` string, uuid: The library file this transcript belongs to when file_uuid is audio taken from it (e.g. a video's sound track). Defaults to file_uuid.
  - `reuse` boolean: true: when the source file already has a finished transcript with timing (or one still running), answer 200 with it and charge nothing.

## Response `200`

reuse: true and the source file already has a transcript; nothing was charged.

- object
  - `success` boolean
  - `data` object
    - `transcription_uuid` string, uuid
    - `job_id` integer, nullable
    - `estimated_cost` number, float: Always 0.
    - `status` string: completed | processing | pending
    - `reused` boolean: Always true.
  - `timestamp` string, date-time

## Other responses

- `202`: Queued.
- `400`: Missing file_uuid, an invalid refinement_type or language, or a non-boolean diarize.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits.
- `404`: Unknown file_uuid, or not yours.
- `415`: The file is neither audio nor video.
- `422`: The audio could not be processed.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)