API Documentation

Quick Start

1

Get API Key

Register an account and create an API key from your dashboard or via the API.

2

Make Requests

Authenticate with Bearer token or X-API-Key header on every request.

3

Transcribe Videos

POST a YouTube URL to /v1/transcribe and get a full transcript back.

Authentication

All API endpoints require authentication via one of two methods:

Bearer Token (JWT)

Obtain a JWT by logging in via POST /auth/login. Include it in the Authorization header.

bash

curl -X POST https://yt2txt.com/v1/transcribe \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

API Key

Create an API key via POST /keys. Include it in the X-API-Key header.

bash

curl -X POST https://yt2txt.com/v1/transcribe \
  -H "X-API-Key: yt2_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

Rate Limits

Rate limits depend on your subscription plan. Exceeding limits returns HTTP 429.

Plan	Requests/hour	Daily minutes	Monthly minutes
Free	5	10	300
Starter	30	100	5,000
Pro	120	300	15,000
Max	300	500	Unlimited

Endpoints

POST /v1/transcribe

Submit a YouTube video for transcription. Returns a job immediately (async) or waits for the result (sync).

Request Body

Field	Type	Required	Description
`url`	string	Yes	YouTube video URL
`async_mode`	boolean	No	If true, returns immediately with a job_id for polling. Default: false

Example

bash

curl -X POST https://yt2txt.com/v1/transcribe \
  -H "X-API-Key: yt2_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

Response (sync)

json

{
  "job_id": "abc123",
  "status": "completed",
  "video_title": "Rick Astley - Never Gonna Give You Up",
  "duration_seconds": 213,
  "segments": [
    {"start": 0.0, "end": 4.5, "text": "We're no strangers to love..."}
  ],
  "full_text": "We're no strangers to love..."
}

Response (async_mode: true)

json

{
  "job_id": "abc123",
  "status": "processing"
}

GET /v1/jobs

List your transcription jobs, paginated.

Query Parameters

Field	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max 100)
`status`	string	—	Filter by status: processing, completed, failed

bash

curl https://yt2txt.com/v1/jobs?page=1&per_page=10 \
  -H "X-API-Key: yt2_your_key"

GET /v1/jobs/{job_id}

Retrieve details of a specific job. Use this to poll async jobs until status is "completed" or "failed".

bash

curl https://yt2txt.com/v1/jobs/abc123 \
  -H "X-API-Key: yt2_your_key"

POST /v1/jobs/{job_id}/actions/{action}

Run AI post-processing on a completed transcript.

Available Actions

Action	Description
`summarize`	Generate a concise summary of the transcript
`chapters`	Create timestamped chapters
`keywords`	Extract key topics and keywords
`translate`	Translate the transcript
`quiz`	Generate quiz questions from the content

Example

bash

curl -X POST https://yt2txt.com/v1/jobs/abc123/actions/summarize \
  -H "X-API-Key: yt2_your_key"

Response

json

{
  "action": "summarize",
  "result": "This video covers the classic 1987 hit..."
}

POST /auth/register

Create a new user account.

Request Body

json

{
  "email": "[email protected]",
  "password": "your_secure_password"
}

POST /auth/login

Authenticate and receive a JWT token.

Request Body

json

{
  "email": "[email protected]",
  "password": "your_secure_password"
}

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

POST /keys

Create a new API key. Requires Bearer token authentication.

Request Body

json

{
  "name": "my-integration"
}

Response

json

{
  "id": "key_abc123",
  "name": "my-integration",
  "key": "yt2_live_abc123...",
  "created_at": "2026-03-17T12:00:00Z"
}

GET /keys

List all your API keys (key values are masked).

DELETE /keys/{key_id}

Revoke an API key. This action cannot be undone.

Error Handling

All errors follow a consistent JSON format:

json

{
  "detail": "Description of what went wrong"
}

Status Code	Description
`400`	Bad Request — invalid parameters or missing required fields
`401`	Unauthorized — missing or invalid authentication
`403`	Forbidden — insufficient permissions or quota exceeded
`404`	Not Found — resource does not exist
`422`	Unprocessable Entity — validation error in request body
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — unexpected failure

Interactive Explorer

Try out the API directly from your browser using Swagger UI. Authenticate with your token to make live requests.

Scroll down or click to load the API Explorer