Skip to main content
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

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):
In a webhook the same fields sit directly on data (data.text, data.data.segments) instead of under result.

Captions or speech-to-text

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:
Retry with "provider": "importly" to accept the quote.
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. 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.

Transcripts inside an import

To get the file and its transcript from one job, add includeTranscript: true to POST /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

Failed transcriptions are refunded automatically. See Pricing & credits.

Full reference: POST /transcribe

Every parameter, provider options, and the status endpoint.