# Overview

Castmagic is an all-in-one transcription & AI-content platform powering content creators and businesses of all kinds.

Use cases supported by Castmagic API:

* [Transcription](/endpoints/transcripts) — Speaker diarization, English + 17 additional languages.
* Content Generation (in development) — Intelligent content production for transcripts.

Continue to our Quick Start documentation to submit your first transcription request.


# Quick Start

Transcribe your first audio URL with a cURL.

The following minimal request is enough to transcribe your first audio:

```
curl https://app.castmagic.io/v1/transcripts \
    -X POST \
    -H "Authorization: Bearer API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{"url": "AUDIO_URL"}'
```

Castmagic endpoints accept and respond with JSON. Continue to Authentication for more information on generating and using API secrets.


# Authentication

Authenticate with Castmagic API with a secret key.

Generate a new API secret in your [Castmagic developer dashboard](https://app.castmagic.io/developer). If you don't have a developer dashboard, reach out to <justin@castmagic.io> for access.

Once you have an API secret, include it with an Authorization header in each request:

```
Authorization: Bearer API_SECRET
```

Keep your API secret safe! You can generate as many as you would like, however we're unable to reveal your secret again once it has been generated.


# Transcripts

Transcribe audio from a URL.

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.

Transcription supports speaker diarization by default. You will find paragraphs labled 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).

## 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 file to transcribe                                                                               |
| boosted\_words                        | String\[] | List of words to boost when transcribing                                                                |
| language\_code                        | String    | Language code. Defaults to `"en"`. See Supported Languages section for all language codes               |
| language\_detection                   | Boolean   | Attempt to automatically detect the content language. Will be overridden by `language_code` if included |

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

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

{% endtab %}

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

```
{
    "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`

#### 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" %}

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

{% endtab %}

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

```
{
    "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 Transcription completed successfully" %}

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

{% endtab %}
{% endtabs %}


# Supported Formats

File formats supported by Castmagic API.

The following file / URL formats are supported:

* `aac`
* `m4a`
* `mp4`
* `mpeg`
* `wav`
* Public YouTube videos

To request another format, please contact <justin@castmagic.io>, thanks!


# Supported Languages

Languages supported by Castmagic API.

The langauges supported by the API are the same that are supported in our customer-facing application. They are:

* `en` — English (default)
* `de` — German
* `es` — Spanish
* `fr` — French
* `hi` — Hindi
* `id` — Indonesian
* `it` — Italian
* `ja` — Japanese
* `ko` — Korean
* `nl` — Dutch
* `no` — Norwegian
* `pl` — Polish
* `pt` — Portuguese
* `ru` — Russian
* `sv` — Swedish
* `tr` — Turkish
* `uk` — Ukrainian
* `zh` — Mandarin (Simplified)

Transcription supports auto-detecting audio language, however results will be higher quality if the correct language is specified.

**Note:** If the language code specified is different from the audio language (i.e. English was specified for an English podcast) the result will likely be much poorer than if auto detection was used.

**Note:** At the moment, the best way to handle multi-lingual audio is to use auto detection.


# Webhooks

How to use Castmagic API webhooks to receive real-time updates.

:hourglass\_flowing\_sand:*Webhook support is on the way!*