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