Reference
REST API
Endpoint reference for the YouTube Translate HTTP API, including accounts, quotes, processing, and artifact reads.
Base URL: https://api.youtubetranslate.com. All JSON endpoints live under /api.
Authentication
Two credential types are accepted:
| Method | Header | Use |
|---|---|---|
| API key | X-API-Key: ytt_live_... |
Scripts and backends |
| OAuth | Authorization: Bearer <token> |
MCP clients |
Account-owned credentials are required for work that spends credits. Reads against the demo need no credentials at all.
Every rate-limited response carries standard RateLimit-* headers. Limits are per key; see Limits and retention.
Accounts
POST /api/accounts
Creates an account and returns an API key exactly once.
curl -X POST https://api.youtubetranslate.com/api/accounts \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","accept_terms":true}'
{
"account_id": "account:96b9730e-a616-4392-a691-8c2629dd8f39",
"api_key": "ytt_live_...",
"warning": "Shown once. Store this credential securely."
}
accept_terms must be true, after reading /terms and /privacy. Registration is limited to five attempts per hour per address.
GET /api/account
Returns the account ID and balance in microcredits.
{
"account_id": "account:96b9730e-...",
"balance": { "available": 990000, "reserved": 0 },
"paid_processing_enabled": true,
"mode": "live"
}
reserved is the hold placed by in-flight jobs. It returns to available when the job settles.
Quotes
POST /api/processing/quote
Returns the cost ceiling for an operation without starting it.
curl -X POST https://api.youtubetranslate.com/api/processing/quote \
-H "X-API-Key: $YTT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"operation":"transcribe","url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","language":"en"}'
{
"mode": "live",
"quote": {
"operation": "transcribe",
"internalId": "517acae2-4a13-4129-96f6-230fad1c7ffb",
"artifactKey": "api/videos/517acae2-.../transcript.json",
"maximumCreditUnits": 300000,
"cached": false,
"priceVersion": "2026-10-27-v1",
"maxSourceSeconds": 1800
},
"balance": { "available": 990000, "reserved": 0 }
}
For translate and summarize, pass video_id instead of url. cached: true means the artifact already exists and the call is a cheap read.
Processing
POST /api/videos
Transcribes a public video.
| Field | Type | Required | Notes |
|---|---|---|---|
url |
string | yes | Public YouTube URL |
language |
string | no | Defaults to en |
max_credit_units |
integer | for uncached | At least the quoted maximum |
Cached video: 200 with the transcript inline.
New video: 202 with job_id and status: "processing".
Missing budget: 428 with code budget_required, plus the quote.
curl -X POST https://api.youtubetranslate.com/api/videos \
-H "X-API-Key: $YTT_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: my-request-001' \
-d '{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","language":"en","max_credit_units":300000}'
Send Idempotency-Key on any spending request you might retry. Reusing a key with a different payload returns 409.
POST /api/videos/:id/translate
| Field | Type | Required |
|---|---|---|
language |
string | yes |
max_credit_units |
integer | for uncached |
POST /api/videos/:id/summarize
| Field | Type | Required |
|---|---|---|
language |
string | no |
length |
string | no, short medium long |
max_credit_units |
integer | for uncached |
POST /api/videos/:id/subtitles
| Field | Type | Required |
|---|---|---|
language |
string | no |
format |
string | no, srt or vtt |
max_credit_units |
integer | for uncached |
POST /api/videos/:id/search
| Field | Type | Required |
|---|---|---|
query |
string | yes |
language |
string | no |
GET /api/jobs/:id
Returns job status: processing, completed, or failed.
Reads
These never start provider work. They return 404 until the artifact exists.
| Endpoint | Returns |
|---|---|
GET /api/videos/:id |
Video metadata |
GET /api/videos/:id/transcript |
Transcript, optionally ?include_timestamps=true |
GET /api/videos/:id/transcript/:language |
Transcript in a specific language |
GET /api/videos/:id/transcript/languages |
Languages available for this video |
GET /api/videos/:id/translations |
All retained translations |
GET /api/videos/:id/summary?language=en |
Summary |
GET /api/videos/:id/subtitles?language=en&format=srt |
SRT or VTT file |
Demo
No credentials required, restricted to two allowlisted videos.
| Endpoint | Returns |
|---|---|
GET /api/demo/examples |
The demo video list |
GET /api/demo/transcript?url=... |
Transcript for a demo video |
Billing
| Endpoint | Purpose |
|---|---|
POST /api/billing/checkouts |
Create a prepaid credit checkout ({"pack":"starter"}) |
GET /pay/:token |
Hosted Stripe Link payment page |
GET /pay/:token/status |
Whether the purchase settled |
POST /api/billing/checkouts
Requires an account API key, not an OAuth token or the website session.
{
"checkout_url": "https://api.youtubetranslate.com/pay/...",
"amount_cents": 100,
"credit_units": 1000000,
"mode": "live",
"payment_method": "link"
}
Credit is granted only after Stripe confirms a settled Link payment. See Pricing and credits.
Service
| Endpoint | Purpose |
|---|---|
GET /api/health |
200 when the API and database are healthy, 503 otherwise |
GET /llms.txt |
Agent brief |
GET /.well-known/oauth-authorization-server |
OAuth metadata |