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
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
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 thanwait. 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 awebhookUrl instead of waiting, and store the jobId with the record:
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
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 toPOST /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.