> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/endpoints/transcripts.md).

# Transcripts

Transcribe audio or video from a URL, without creating a recording.

At the core of Castmagic is transcription. Transcription is an async process and can vary in duration based on factors such as audio language, however it is typically complete in around 15 minutes or less.

This endpoint transcribes a **public media URL directly**, without creating a recording. For the recording-centric flow (uploads, imports, content generation, renders) see [Recordings](/endpoints/recordings.md).

Transcription supports speaker diarization by default. You will find paragraphs labeled by speaker in the `"utterances"` key of a completed transcript response.

[See a sample of a full transcript JSON](https://gist.githubusercontent.com/jtormey/00fa4944c5af3a04cd54a6ae70fe2ecb/raw/0e420ae370f42f8b7c20ceac86b3e2bdba3e7f38/castmagic_sample_transcript.json).

{% hint style="info" %}
**Tier:** `core`. Base URL `https://app.castmagic.io`.
{% endhint %}

{% hint style="warning" %}
**Migrating from an earlier version of these docs?** Two things changed:

* `audio_duration` is now in **minutes** (it was previously documented in seconds).
* The `language_detection` parameter was **removed**. Auto-detection is now the default — `language_code` defaults to `"auto"`.

Both have been live for some time; integrations that follow the current behavior below need no changes.
{% endhint %}

## Submit a request to transcribe from a URL

<mark style="color:green;">`POST`</mark> `https://app.castmagic.io/v1/transcripts`

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_SECRET |

#### Request Body

| Name                                  | Type      | Description                                                                                                     |
| ------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| url<mark style="color:red;">\*</mark> | String    | URL of the media file to transcribe                                                                             |
| language\_code                        | String    | Language code. Defaults to `"auto"` (auto-detect). See [Supported Languages](/reference/supported-languages.md) |
| boosted\_words                        | String\[] | List of words to bias recognition toward                                                                        |

{% hint style="info" %}
`language_code` defaults to `"auto"`, which auto-detects the spoken language. Pass an explicit code (e.g. `"en"`) only when you know it — results are best when the code matches the audio.
{% endhint %}

{% tabs %}
{% tab title="201: Created Request to transcribe was successful" %}

```json
{
    "id": "ae844ebc-ad12-444e-8310-1049a12cf139",
    "status": "queued"
}
```

{% endtab %}

{% tab title="400: Bad Request Request included a bad parameter" %}

```json
{
    "errors": {
        "url": [
            "must be a valid url"
        ]
    },
    "valid": false
}
```

{% endtab %}
{% endtabs %}

## Fetch details for a transcript given an identifier

<mark style="color:blue;">`GET`</mark> `https://app.castmagic.io/v1/transcripts/:id`

Poll this endpoint until `status` is `"completed"`. Statuses are `queued`, `processing`, `completed`, `error`, and `canceled`. Error and canceled responses include an `"error"` string describing the failure.

#### Path Parameters

| Name                                 | Type   | Description                 |
| ------------------------------------ | ------ | --------------------------- |
| id<mark style="color:red;">\*</mark> | String | ID of the transcript to get |

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_SECRET |

{% tabs %}
{% tab title="200: OK Transcript is processing" %}

```json
{
    "id": "ae844ebc-ad12-444e-8310-1049a12cf139",
    "status": "processing"
}
```

{% endtab %}

{% tab title="200: OK Transcription completed successfully" %}

```json
{
    "id": "ae844ebc-ad12-444e-8310-1049a12cf139",
    "status": "completed",
    "audio_duration": 42,
    "utterances": [...]
}
```

{% endtab %}

{% tab title="200: OK Transcript is in error state" %}

```json
{
    "id": "ae844ebc-ad12-444e-8310-1049a12cf139",
    "status": "error",
    "error": "Video to audio conversion error, could not transcode from video/mp4"
}
```

{% endtab %}

{% tab title="200: OK Transcript not found" %}

```json
{
    "errors": {
        "id": "not found"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
`audio_duration` is expressed in **minutes** (e.g. `42` for a 42-minute file), not seconds.
{% endhint %}