1. Add your key
Create your key on the API key page (it’s shown once) and add it to.env.local, and to your host’s environment variables (on Vercel: Settings → Environment Variables):
.env.local
NEXT_PUBLIC_: that would ship it to the browser.
2. Start the transcript
This route handler sends the link to Importly."mode": "auto" uses the video’s captions and falls back to speech-to-text when there are none, and wait holds the request until the transcript is ready, so a captioned video usually comes back in this one call.
app/api/transcribe/route.ts
lib/importly.ts
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, and the browser asks this route until it’s done:
app/api/transcribe/[id]/route.ts
4. The form
app/transcript-form.tsx
segments holds the same transcript with start and end times in seconds, for captions, chapters or search.
5. In production: save results with a webhook
When the transcript belongs to a record in your database (a saved video, a user’s library), don’t keep the browser waiting. Start the job with awebhookUrl and save the result when Importly calls you back:
jobId with your record. Importly sends one POST when the job finishes. This handler takes only the jobId from it and reads the result from the API with your key, so a forged request can’t put data into your app. Every delivery is also signed: to reject forged requests before calling the API, check the Importly-Signature header as shown in Verify signatures:
app/api/webhooks/importly/route.ts
https://, so a localhost app gets nothing: use polling 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 (recipe). /import has no wait, so use polling or 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.