Transcribe Endpoint

The transcribe endpoint provides two operations:

POST https://api.importly.io/transcribe - Start a new transcription
GET https://api.importly.io/transcribe/status?id={id} - Check transcription status

Purpose

Turn a media URL into a transcript: clean text plus timestamped segments. For YouTube URLs with captions (including auto-generated ones), extraction is fully managed and costs $0.01 per video. For caption-less media, use Importly's built-in AI transcription with "provider": "importly" — no speech-to-text account needed — at $0.02 per media-minute (min $0.03). Or bring your own provider (AssemblyAI, Deepgram, or OpenAI) at $0.01 per media-minute (min $0.03) plus your provider's own usage fees. AI transcription (built-in or BYOK) also downloads the media to extract its audio; that download bills at the standard $0.01 per MB downloaded and is itemized as downloadCostInDollars in the job result.

Parameters

Parameter	Type	Description
`url`*	`string`	Publicly accessible media URL to transcribe.
`language`	`string`	Language code (e.g., `en`). Auto-detected when omitted.
`provider`	`string`	AI transcription provider for caption-less media: `importly` (built-in, no API key needed), `assemblyai`, `deepgram`, or `openai`. When omitted, Importly extracts existing captions.
`apiKey`	`string`	Your API key for the chosen provider. Not needed for `importly`. Optional if you have stored one via `POST /transcription-provider`.
`providerOptions`	`object`	Provider-specific options, passed through unchanged.
`maxCostDollars`	`number`	Optional spending ceiling for built-in transcription. Required when media duration can't be determined up front — the unused portion is refunded after transcription.
`webhookUrl`	`string`	URL to receive a callback notification when the transcript is ready.

Authentication is required via the Authorization: Bearer <API_KEY> header.

Example Request (YouTube captions)

bash
1curl -X POST "https://api.importly.io/transcribe" \
2     -H "Authorization: Bearer YOUR_API_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{
5       "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
6       "webhookUrl": "https://your-app.com/api/importly-webhook"
7     }'

Example Request (built-in AI transcription)

bash
1curl -X POST "https://api.importly.io/transcribe" \
2     -H "Authorization: Bearer YOUR_API_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{
5       "url": "https://example.com/conference-talk.mp4",
6       "provider": "importly"
7     }'

Example Request (AI transcription with your provider key)

bash
1curl -X POST "https://api.importly.io/transcribe" \
2     -H "Authorization: Bearer YOUR_API_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{
5       "url": "https://example.com/podcast-episode.mp3",
6       "provider": "deepgram",
7       "apiKey": "YOUR_DEEPGRAM_KEY",
8       "language": "en"
9     }'

Response

json
1{
2  "success": true,
3  "data": {
4    "jobId": "b2f7c9e4-…",
5    "status": "queued",
6    "message": "Transcription has been queued for processing."
7  }
8}

Checking Status

bash
1curl "https://api.importly.io/transcribe/status?id={jobId}" \
2     -H "Authorization: Bearer YOUR_API_KEY"

When the job completes, the response includes the transcript:

json
1{
2  "success": true,
3  "data": {
4    "jobId": "b2f7c9e4-…",
5    "status": "completed",
6    "result": {
7      "text": "Full transcript text…",
8      "source": "platform_captions",
9      "language": "en",
10      "duration": 212,
11      "data": {
12        "segments": [
13          { "start": 0.0, "end": 4.2, "text": "First segment…" }
14        ]
15      },
16      "costInDollars": 0.01
17    }
18  }
19}

If no captions are available and no provider is given, the job fails with code TRANSCRIPTION_PROVIDER_REQUIRED and a quote object (estimatedMinutes, estimatedCostDollars) telling you exactly what built-in transcription would cost for that video — retry with "provider": "importly" to accept it. Nothing is charged for failed jobs: charges for failed transcriptions are automatically refunded.

See also: Import Endpoint for downloading the media itself, and Webhooks for callback delivery details.

Import Balance