DEV Community

Yusuf Yildiz
Yusuf Yildiz

Posted on Originally published at importly.io

Adding paste-a-link transcripts to a Next.js app (that still work once deployed)

A lot of apps want the same small feature: a user pastes a YouTube, TikTok or podcast link and gets the transcript back, to summarize it, search it or feed it to a model. It looks like an afternoon of work. Then it ships and the problems start.

The usual first version uses a captions library. It works on your laptop. Once it's deployed, two things go wrong. Requests from cloud servers (Vercel, AWS, a VPS) get blocked or asked to sign in, so the same code that worked locally returns errors in production. And plenty of videos have no captions at all, so you need a speech-to-text fallback, which means downloading the audio and calling a second service.

I built Importly for this, so this post uses it. It's an API: you send it a link and get back the transcript, the file or the metadata, and it works from servers. Below is the Next.js App Router version I'd ship, with the key kept on the server.

1. Add your key

Create a key in the dashboard and put it in .env.local and in your host's environment variables:

IMPORTLY_API_KEY=your_api_key
Enter fullscreen mode Exit fullscreen mode

Don't prefix it with NEXT_PUBLIC_. The browser should only talk to your own route handlers.

2. One route handler for 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. maxCostDollars stops a long video without captions before it's charged.

// app/api/transcribe/route.ts
import { toResult } from '@/lib/importly'

export const maxDuration = 60

export async function POST(request: Request) {
  const { url } = await request.json()

  const res = await fetch('https://api.importly.io/transcribe', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.IMPORTLY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url, mode: 'auto', wait: 25, maxCostDollars: 0.5 }),
  })

  const body = await res.json()
  if (!res.ok || !body.success) {
    return Response.json({ status: 'failed', message: body.error, code: body.code }, { status: res.status })
  }

  return Response.json(toResult(body.data))
}
Enter fullscreen mode Exit fullscreen mode
// lib/importly.ts
export const toResult = (data: any) => ({
  jobId: data.jobId,
  status: data.status,
  text: data.result?.text,
  segments: data.result?.data?.segments,
  message: data.message,
  code: data.code,
})
Enter fullscreen mode Exit fullscreen mode

segments has the same transcript with start and end times in seconds, which is what you want for captions, chapters or jumping to a timestamp.

3. Poll when it's still running

A long video with no captions takes longer than wait. Then you get status: 'queued' or 'running' and a jobId, and the browser asks this route until it's done:

// app/api/transcribe/[id]/route.ts
import { toResult } from '@/lib/importly'

export async function GET(_request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params

  const res = await fetch(`https://api.importly.io/transcribe/status?id=${encodeURIComponent(id)}`, {
    headers: { Authorization: `Bearer ${process.env.IMPORTLY_API_KEY}` },
    cache: 'no-store',
  })

  const body = await res.json()
  if (!res.ok || !body.success) {
    return Response.json({ status: 'failed', message: body.error, code: body.code }, { status: res.status })
  }

  return Response.json(toResult(body.data))
}
Enter fullscreen mode Exit fullscreen mode

The client form is a normal useState form that POSTs the link, then calls the status route every few seconds while the status is queued or running. The full component is in the docs.

4. In production, use a webhook

If the transcript belongs to a record in your database, don't keep the browser waiting. Start the job with a webhookUrl, store the jobId on your record, and save the result when the callback arrives. In the handler I only take the jobId from the request and read the result from the API with my own key, so a forged request can't put data into the app. Deliveries are also signed with an Importly-Signature header if you want to reject forged requests up front.

Two things to know: the webhook URL has to be public https://, so it does nothing on localhost (use polling in development), and each job gets one delivery, so it's worth a small sweep that checks jobs pending for more than a few minutes.

What it costs

A transcript from captions is $0.003. Speech-to-text for a video without captions is $0.01 per minute. It's free to try, no card required.

The full recipe, including the form component, the webhook handler and downloading the file instead of the transcript, is here: Add transcripts to a Next.js app.

If you're using Claude Code or Cursor on the app, you can also point it at the Importly MCP server and ask it to add this for you. It reads the same guide.

Top comments (0)