How to get a speaker-labeled transcript from a YouTube URL

Who this is for

This guide answers: how do I get a diarized / speaker-labeled transcript from a YouTube URL in my pipeline?You get a plain REST flow that returns speaker-aware captions you can feed into summarizers, RAG indexes, subtitle tools, or agent workflows. No SDK required.

• Base URL: https://diarize.io
• Auth: Authorization: Bearer YOUR_API_KEY
• Sources: YouTube, X, Instagram, and TikTok (this guide focuses on YouTube)

Step 1

How do I get a diarize API key?

1. Sign up at diarize.io. New accounts get 180 free minutes, up to 60 a day. No credit card.
2. Create a key on the API keys page.
3. Pass the key on every request. Keys are scoped to your account and consume your minute balance.

Authorization: Bearer YOUR_API_KEY

Step 2

How do I submit a YouTube URL?

Create a job with POST /api/v1/jobs. Send sourceUrl (legacy youtubeUrl still works).

curl -X POST https://diarize.io/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

{
  "jobId": "job_abc123",
  "status": "CREATED",
  "estimatedTime": 90
}

Step 3

How do I poll for the result?

Check progress with GET /api/v1/jobs/:jobId. Wait until COMPLETED before downloading.

curl https://diarize.io/api/v1/jobs/job_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "jobId": "job_abc123",
  "status": "COMPLETED",
  "progress": "100%",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:32:00Z",
  "error": null
}

Step 4

How do I download the speaker-labeled transcript?

Once status is COMPLETED, call GET /api/v1/jobs/:jobId/transcript/:format. Incomplete jobs return 409 Conflict.

curl https://diarize.io/api/v1/jobs/job_abc123/transcript/json \
  -H "Authorization: Bearer YOUR_API_KEY"

TypeScript fetch example

Same endpoints as the curl examples above: submit, poll, then download.

const API = "https://diarize.io/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.DIARIZE_API_KEY}`,
  "Content-Type": "application/json",
};

async function getYoutubeTranscript(sourceUrl: string, format = "json") {
  const create = await fetch(`${API}/jobs`, {
    method: "POST",
    headers,
    body: JSON.stringify({ sourceUrl }),
  });
  const { jobId, status } = await create.json();

  let current = status as string;
  while (current !== "COMPLETED" && current !== "FAILED" && current !== "REJECTED") {
    await new Promise((r) => setTimeout(r, 10_000));
    const poll = await fetch(`${API}/jobs/${jobId}`, { headers });
    const body = await poll.json();
    current = body.status;
  }

  if (current !== "COMPLETED") {
    throw new Error(`Job ${jobId} ended with status ${current}`);
  }

  const transcript = await fetch(`${API}/jobs/${jobId}/transcript/${format}`, {
    headers: { Authorization: headers.Authorization },
  });
  return format === "json" ? transcript.json() : transcript.text();
}

Which transcript format should I choose?

Paid minute packages (after your free minutes): $10 → 200 minutes, $25 → 1,000 minutes. See pricing.

FAQ

How do I get a speaker-labeled transcript from a YouTube URL via API?

Create an API key at diarize.io/settings/api-keys, POST the YouTube URL to https://diarize.io/api/v1/jobs with Authorization: Bearer YOUR_API_KEY, poll GET /api/v1/jobs/:jobId until status is COMPLETED, then download with GET /api/v1/jobs/:jobId/transcript/:format where format is json, txt, srt, or vtt.

What output formats does the diarize transcript API support?

The download endpoint supports json, txt, srt, and vtt. Use json for structured pipeline work, txt for readable text, and srt or vtt for subtitle workflows.

How long does a YouTube transcription job take?

The create-job response includes estimatedTime in seconds (docs examples show 90). If a transcript already exists for the same source, the API may return 200 OK with status COMPLETED immediately.

Do I need a credit card to try the API?

No. New accounts get 180 free minutes, up to 60 a day, with no credit card. Paid packages are $10 for 200 minutes and $25 for 1,000 minutes. API keys consume your account minute balance.