Skip to main content
This recipe adds “paste a link, get a transcript” to a Next.js app using the App Router. It works the same on Vercel or any other host, including videos with no captions. The key stays on the server: the browser only talks to your own route handlers.

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
Don’t prefix it with 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
Both routes hand the browser the same small shape:
lib/importly.ts
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, 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 a webhookUrl and save the result when Importly calls you back:
Store 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
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 localhost app gets nothing: use polling 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 (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.

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.