Skip to main content
This recipe adds “send a link, get a transcript” to a Python backend with FastAPI. It covers videos without captions too, and the calls are plain HTTP, so they move to Flask, Django or a background worker unchanged. The key stays on your server.

1. Add your key

Create your key on the API key page (it’s shown once) and put it in your server’s environment:
.env
Install the two packages the code uses:

2. Start the transcript

"mode": "auto" uses the video’s captions and falls back to speech-to-text when there are none. wait holds the request until the transcript is ready, so a captioned video usually comes back in this one call.
main.py
A rejected request (a bad link, a key problem, or a low balance) comes back with an HTTP error and an error message. A job that fails later, for example because the video is private, comes back with status: "failed", a code and a message. See Error handling.

3. Poll if it’s still running

Long videos without captions take longer than wait. Then the response has status: "queued" or "running" and a jobId. Your frontend calls this endpoint every few seconds until the status is completed or failed:
main.py
text is the whole transcript. segments holds the same text with start and end times in seconds, which is what you want for chunking into a vector store, captions or search.

4. In production: save results with a webhook

When the transcript belongs to a record in your database, start the job with a webhookUrl instead of waiting, and store the jobId with the record:
Importly sends one POST when the job finishes. The webhook isn’t signed, so this endpoint takes only the jobId from it and reads the result from the API with your key:
main.py
Each job gets one delivery and no retries, so also check jobs that have been pending for a few minutes with the status endpoint. The webhook URL must be public https://, so a server on localhost gets nothing: poll in development. See Webhooks.

Downloading the file instead

For the video or audio file itself, send the link to POST /import and read GET /import/status the same way. The finished job has result.mediaUrl, a link to the file that’s valid for 7 days. Set includeVideo: false for audio only, or store: true to have it copied to your own bucket. /import has no wait, so poll or use a webhook. See Downloads.
A transcript from captions costs $0.003. Speech-to-text for a video without captions is $0.01 per minute, and maxCostDollars stops a long one before it’s charged. Try it free, no card required. See Pricing & credits.

Let your agent write it

Using Claude Code or Cursor on this app? Connect the MCP server and ask it to add transcripts with Importly: it reads the same integration guide and can test with a real link first. See Build with your agent.