> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcripts

> Get a timestamped transcript for any public video or audio URL. Importly uses the video's own captions when it has them and AI speech-to-text when it doesn't.

Plenty of videos have no captions, and running speech-to-text yourself means downloading the media, extracting the audio, and paying for a separate account. Importly returns the video's own captions when it has them, for \$0.01. When it doesn't, one extra parameter runs speech-to-text on the same URL.

## Quick start

### Request

```bash cURL theme={null}
curl -X POST https://api.importly.io/transcribe \
  -H "Authorization: Bearer $IMPORTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "webhookUrl": "https://your-app.com/webhooks/importly"
  }'
```

```javascript Node.js theme={null}
const res = await fetch('https://api.importly.io/transcribe', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMPORTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
    webhookUrl: 'https://your-app.com/webhooks/importly',
  }),
})
const { data } = await res.json()
console.log(data.jobId)
```

```python Python theme={null}
import os
import requests

res = requests.post(
    "https://api.importly.io/transcribe",
    headers={"Authorization": f"Bearer {os.environ['IMPORTLY_API_KEY']}"},
    json={
        "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
        "webhookUrl": "https://your-app.com/webhooks/importly",
    },
)
print(res.json()["data"]["jobId"])
```

### Response

Poll `GET /transcribe/status?id={jobId}`, or wait for the webhook. A completed job has the full text and timestamped segments (times in seconds):

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "95be812f-4a2c-410a-9fcb-3ca5b445cc44",
    "status": "completed",
    "result": {
      "text": "All right, so here we are, in front of the elephants\nthe cool thing about these guys is that they have really...\nreally really long trunks\nand that's cool\n(baaaaaaaaaaahhh!!)\nand that's pretty much all there is to say",
      "source": "platform_captions",
      "language": "en",
      "duration": 19,
      "data": {
        "segments": [
          { "start": 1.2, "end": 3.36, "text": "All right, so here we are, in front of the elephants" },
          { "start": 5.318, "end": 7.974, "text": "the cool thing about these guys is that they have really..." },
          { "start": 7.974, "end": 12.616, "text": "really really long trunks" }
        ]
      },
      "costInDollars": 0.01
    }
  }
}
```

In a webhook the same fields sit directly on `data` (`data.text`, `data.data.segments`) instead of under `result`.

## Captions or speech-to-text

| Source | How to ask for it | Price |
| - | - | - |
| The video's own captions, including auto-generated ones | Omit `provider` | \$0.01 per video |
| Importly speech-to-text | `"provider": "importly"` | $0.02 per media minute ($0.03 minimum), plus the audio download |
| Your own AssemblyAI, Deepgram, or OpenAI key | `"provider": "assemblyai"` (or `deepgram`, `openai`) and `"apiKey"` | $0.01 per media minute ($0.03 minimum), plus the audio download and your provider's own fees |

Setting `provider` (or `providerOptions`) always runs speech-to-text and skips captions, so leave it out unless the video has none. Speech-to-text downloads the media to extract its audio. That download is billed at \$0.01 per MB and itemized as `downloadCostInDollars` in the result.

### When a video has no captions

Without a `provider`, a video with no captions fails with `TRANSCRIPTION_PROVIDER_REQUIRED` and a quote for speech-to-text. Nothing is charged:

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "95be812f-4a2c-410a-9fcb-3ca5b445cc44",
    "status": "failed",
    "message": "This video has no captions. Add \"provider\": \"importly\" to transcribe it with AI speech-to-text — this 1-min video would cost $0.03 from your credits ($0.02/min). Or bring your own key (deepgram, openai, assemblyai) at $0.01/min.",
    "code": "TRANSCRIPTION_PROVIDER_REQUIRED",
    "quote": { "provider": "importly", "estimatedMinutes": 1, "estimatedCostDollars": 0.03 }
  }
}
```

Retry with `"provider": "importly"` to accept the quote.

> [!TIP]
>
> Set `maxCostDollars` to cap the per-minute charge on long media. If the estimate is over the cap, the job fails with `MAX_COST_EXCEEDED` and the estimate instead of running. The cap doesn't include the audio download.

## Languages

Pass `language` as a two-letter code, such as `es`.

| Source | What `language` does | Without it |
| - | - | - |
| Captions | Picks that caption track | English if the video has it, otherwise the first track |
| Speech-to-text | Sent to the provider as its language setting | `importly`, `deepgram`, and `assemblyai` transcribe as English; `openai` detects the language |

Set it for non-English media whenever you use speech-to-text.

Provider-specific options such as AssemblyAI's `speaker_labels` go in `providerOptions`. See [provider options](/docs/endpoints/transcribe.md#provider-options).

## Transcripts inside an import

To get the file and its transcript from one job, add `includeTranscript: true` to [`POST /import`](/docs/endpoints/import). The result gains a `transcript` object, billed like a separate transcription. Use `transcriptProvider`, `transcriptApiKey`, `transcriptLanguage`, and `transcriptOptions` the same way as `provider`, `apiKey`, `language`, and `providerOptions` here. If no transcript can be produced, the import still succeeds and `transcript` is `{ "status": "skipped", "reason": "…" }`.

## Pricing

| Example | Cost |
| - | - |
| Caption transcript of a YouTube video | \$0.01 |
| 10-minute podcast with Importly speech-to-text | about $0.30 ($0.20 for speech-to-text plus the audio download) |

Failed transcriptions are refunded automatically. See [Pricing & credits](/docs/billing.md).

> [card] [Full reference: POST /transcribe](/docs/endpoints/transcribe.md)
>
> Every parameter, provider options, and the status endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.