Importly

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, connect your own AI transcription provider (AssemblyAI, Deepgram, or OpenAI) and Importly orchestrates the full download-and-transcribe pipeline for $0.03 per job plus your provider's own usage fees.

Parameters

ParameterTypeDescription
url*string

Publicly accessible media URL to transcribe.

languagestring

Language code (e.g., en). Auto-detected when omitted.

providerstring

AI transcription provider for caption-less media: assemblyai, deepgram, or openai. When omitted, Importly extracts existing captions.

apiKeystring

Your API key for the chosen provider. Optional if you have stored one via POST /transcription-provider.

providerOptionsobject

Provider-specific options, passed through unchanged.

webhookUrlstring

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 (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      "language": "en",
9      "duration": 212,
10      "data": {
11        "segments": [
12          { "start": 0.0, "end": 4.2, "text": "First segment…" }
13        ]
14      }
15    }
16  }
17}

If no captions are available and no provider is configured, the job fails with a message asking you to supply a provider and apiKey — nothing is charged for failed jobs beyond the attempted work.

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

ImportFormat selectors