---
title: "Transcribe media"
method: POST
path: "/transcribe"
tags: ["Transcribe"]
---

# Transcribe media

`POST /transcribe`

## Request

- Base URL: `https://www.happyscribe.com/api/v1`
- URL: `https://www.happyscribe.com/api/v1/transcribe`
- Auth: API key in header `Authorization`

Creates a transcription order from a media URL. By default the order is submitted
immediately (`confirm: true`) and processing starts as soon as the file is
ingested. Pass `confirm: false` to preview pricing first, then submit with
`POST /orders/{id}/confirm`.

The media `url` must be publicly accessible during ingestion. Once ingested, the
file can safely be deleted from its source. Poll the order or use `webhook_url`
to be notified of state changes.

## Request body

- TranscribeRequest
  - `url` string, required: URL of the media file. Must be publicly accessible during ingestion.
  - `language` string, required: BCP-47 language code of the media. See [Languages](/api-reference/languages).
  - `workspace_id` string: ID of the workspace where the file is created. Required unless `folder_id` is given, in which case it is inferred from the folder. A `wks_` id; integer workspace ids are still accepted.
  - `service` 'auto' | 'pro': `auto` for machine-made, `pro` for human-made.
  - `confirm` boolean: When `false`, the order stays `incomplete` until submitted via `POST /orders/{id}/confirm`.
  - `folder_id` integer: ID of the folder to create the order in.
  - `folder` string: Path of the folder to save the result in, e.g. `path/to/my folder`.
  - `name` string: Name of the resulting file. Defaults to a name derived from the source file.
  - `boost` boolean: When `true`, `pro` orders are prioritized for faster turnaround. Has no effect on `auto` orders.
  - `tags` string[]: Tags to add to the resulting file.
  - `webhook_url` string: URL that receives a webhook every time the order changes state.
  - `glossary_ids` string[]: Glossary IDs (`gls_…`) to apply. All IDs must belong to the specified workspace. Integer glossary ids are still accepted.
  - `style_guide_id` integer: Style guide ID to apply. For `pro` orders, addons like verbatim and SDH are applied automatically from the style guide settings.

## Response `200`

The created order.

- Order
  - `id` string: Unique identifier for the order (UUID format).
  - `folder_id` integer
  - `state` 'incomplete' | 'waiting_for_payment' | 'submitted' | 'locked' | 'fulfilled' | 'failed' | 'canceled' | 'expired' | 'free_trial_submitted' | 'free_trial_fulfilled': Current state of the order: - `incomplete` — created but not yet submitted - `waiting_for_payment` — waiting for payment to be processed - `submitted` — submitted, processing in progress - `locked` — insufficient credits or balance; unlock from the UI after topping up - `fulfilled` — completed successfully - `failed` — processing failed; see `failure_reason` - `canceled` — the order was canceled - `expired` — an old failed or incomplete order that has been cleaned up - `free_trial_submitted` / `free_trial_fulfilled` — legacy free-trial states
  - `operations` OrderOperation[]
    - `name` string: The type of operation, e.g. `transcription_translation` or `subtitles`.
    - `type` 'auto' | 'pro': The service level.
    - `language` string: The source language code.
    - `target_language` string: The target language code, for translation operations.
    - `glossary_ids` string[]: Glossary IDs, beginning with `gls_`.
    - `style_guide_id` integer
    - `use_vocab` boolean: Whether vocabulary optimization is used (subtitle operations).
  - `details` OrderDetails: Pricing information and items being processed.
    - `items` object[]
      - `input_id` integer
      - `filename` string
      - `pricing_unit_name` string
      - `pricing_unit_count` number
      - `service` OrderOperation
        - `name` string: The type of operation, e.g. `transcription_translation` or `subtitles`.
        - `type` 'auto' | 'pro': The service level.
        - `language` string: The source language code.
        - `target_language` string: The target language code, for translation operations.
        - `glossary_ids` string[]: Glossary IDs, beginning with `gls_`.
        - `style_guide_id` integer
        - `use_vocab` boolean: Whether vocabulary optimization is used (subtitle operations).
      - `addon_id` integer, nullable
      - `addon_name` string, nullable
      - `turnaround_minutes` integer
      - `cents_per_unit` integer
      - `cents` integer
      - `credits` number, nullable
    - `pricing_unit_name` string
    - `pricing_unit_total_count` number
    - `total_cents` integer
    - `total_credits` number, nullable
    - `currency` string
    - `currency_symbol` string
    - `addons_total_cents` object
    - `minimum_charge` integer
  - `addons` object[]
    - `name` string
  - `inputs` object[]
    - `transcription_id` string
  - `can_be_submitted` boolean
  - `outputs_ids` string[]: IDs (UUIDs) of the generated transcriptions or translations. Only present when the order is fulfilled.
  - `transcriptions` object[]: Generated transcriptions with their state and estimated delivery time.
    - `id` integer
    - `uuid` string
    - `name` string
    - `state` string
    - `language` string
    - `estimated_at` string, date-time
  - `ingestions` Ingestion[]
    - `id` integer
    - `name` string: The name of the file being ingested.
    - `state` 'idle' | 'transferring' | 'transferred' | 'analyzing' | 'done' | 'failed' | 'expired'
    - `failure_reason` 'failed_import' | 'invalid_file' | 'failed_analysis' | 'unknown': Only present when `state` is `failed`: - `failed_import` — the file could not be downloaded (URL errored, private, or expired) - `invalid_file` — the file format is not supported - `failed_analysis` — media metadata could not be extracted - `unknown` — something else went wrong; contact support
    - `failure_message` string: Only present when `state` is `failed`. Human-readable, suitable for displaying to an end user.
  - `failure_reason` 'ingestion_failed' | 'transcription_failed' | 'unknown': Present when `state` is `failed`: - `ingestion_failed` — one or more files could not be imported; inspect `ingestions[]` - `transcription_failed` — the transcription/subtitling step failed; inspect `transcriptions[]` - `unknown` — no identifiable cause; contact support

## Other responses

- `401`: Your API key is missing (`missing_api_key`) or wrong (`invalid_api_key`), or it may not access this resource (`unauthorized`).
- `422`: The request failed validation. Each error names its `field`.

---

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