API Documentation

Quick Start

Create an API key from your API keys page, then make your first request:

Request

POST

curl -X POST https://diarize.io/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"youtubeUrl": "https://youtu.be/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 YouTube video.

Request Body

{
  "youtubeUrl": "https://youtu.be/VIDEO_ID"
}

Response (202 Accepted)

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

Deduplication: If a transcript already exists for this video, 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"

Returns transcript file with appropriate Content-Type and Content-Disposition headers.

Rate Limits

Job creation

10 per minute

Transcript reads

60 per minute

If you exceed rate limits, you'll receive a 429 Too Many Requests response with a Retry-After header.

Error Codes

All errors return JSON with code and message fields:

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API key"
}

Common Error Codes

400 BAD_REQUESTInvalid YouTube URL or missing parameters

401 UNAUTHORIZEDInvalid or missing API key

404 NOT_FOUNDJob not found or not owned by you

413 PAYLOAD_TOO_LARGEVideo exceeds 3-hour limit

429 RATE_LIMITEDToo many requests, retry after indicated seconds

500 INTERNAL_ERRORServer error, contact support if persistent

503 SERVICE_UNAVAILABLETemporarily unavailable, retry later

Need help?

Our team is here to help you integrate successfully.

Contact Support