API Documentation

Quick Start

Create an API key from your API keys page, then submit any supported source URL.

Request

POST

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"}'

Response

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

Authentication

All API requests require an API key passed in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Note: API keys are scoped to your account and consume your minute balance. You can create and revoke keys from your settings.

Endpoints

Create transcription job

POST/api/v1/jobs

Create a new transcription job for a supported source. The request accepts sourceUrl and still accepts the legacy youtubeUrl alias.

Request Body

{
  "sourceUrl": "https://www.youtube.com/watch?v=VIDEO_ID"
}

// Legacy alias still supported
{
  "youtubeUrl": "https://youtu.be/VIDEO_ID"
}

Response (202 Accepted)

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

Deduplication: If a transcript already exists for the same source, you'll receive 200 OK with status: "COMPLETED" immediately.

Get job status

GET/api/v1/jobs/:jobId

Check the status and progress of a transcription job.

Response

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

Status Values

CREATEDJob submitted

DOWNLOADINGExtracting audio

TRANSCRIBINGRunning speech-to-text

CORRECTINGApplying AI corrections

COMPLETEDReady to download

FAILEDCheck error field

Download transcript

GET/api/v1/jobs/:jobId/transcript/:format

Download the completed transcript. Supports json, txt, srt, and vtt formats.

Example

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

The transcript endpoint is available once the job reaches COMPLETED. Requests to incomplete jobs return 409 Conflict.

Supported Sources

diarize accepts supported links from YouTube, X, Instagram, and TikTok. Each submitted URL is normalized to a canonical source key so repeated requests can reuse the same transcript when available.

Error Codes

400 Bad Request

Invalid or unsupported source URL, or missing parameters

401 Unauthorized

Missing or invalid API key

404 Not Found

Job not found or transcript unavailable

409 Conflict

Transcript is still processing or locked

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Unexpected server error