API reference

Base URL: https://api.example.com — auth with Authorization: Bearer sk_… (create keys in the dashboard). All endpoints speak JSON. Jobs are async: submit, then poll. Results are cached — resubmitting an already-processed public video returns instantly.

POST /v1/jobs

Submit a video for transcription (or metadata only).

url (string, required) — a TikTok, YouTube or Instagram video URL
metadataOnly (boolean, default false) — skip transcription; returns title/description/duration/views only
language (string, optional) — 2-letter hint; omit for auto-detect 
curl -X POST https://api.example.com/v1/jobs \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7234567890123456789"}'

{"id": "a1b2c3d4-...", "status": "IN_QUEUE", "cached": false}

GET /v1/jobs/:id

Poll a job. Terminal statuses: COMPLETED, FAILED.

{"id": "a1b2c3d4-...", "status": "COMPLETED",
 "output": {
   "text": "full transcript ...",
   "language": "ar",
   "duration": 42.7,
   "title": "...", "description": "...",
   "segments": [
     {"start": 0.0, "end": 3.2, "text": "first phrase"},
     {"start": 3.2, "end": 6.9, "text": "second phrase"}
   ]
 }}

A completed job with empty text and a positive duration means the audio was processed and contains no speech (music-only video) — that's a result, not an error.

POST /v1/expand

Turn a TikTok profile, YouTube channel/playlist, or YouTube search query into a list of video URLs with listing metadata. Free.

url (string) — profile/channel/playlist URL (or a bare TikTok @handle), OR
search (string) — YouTube keyword search
limit (int, default 30, max 1000) · postedAfter/postedBefore (YYYY-MM-DD) · minViews (int) · sort ("newest" | "mostViewed") 
curl -X POST https://api.example.com/v1/expand \
  -H "Authorization: Bearer sk_..." \
  -d '{"url": "@bromabakery", "limit": 10, "sort": "mostViewed"}'

{"kind": "tiktok-profile", "scanned": 50, "videos": [
  {"url": "https://www.tiktok.com/@bromabakery/video/7...", "title": "...",
   "durationSeconds": 34, "viewCount": 128000, "postedAt": "2026-06-30T..."}, ...]}

POST /v1/translate

Translate a transcript. Billed only when a translation is delivered.

text (string, required, ≤30k chars) · target (string, e.g. "en", "ar") 
{"translation": "translated text ..."}

GET /v1/usage

Your credit balance and month-to-date usage.

{"creditsUsd": 9.94, "videos": 12, "transcripts": 0, "minutes": 4, "translations": 0,
 "freeLimits": {"videos": 25, "transcripts": 1}}

Errors & limits

401 — missing/invalid key · 402 — free-tier cap reached or out of credits (buy a pack in the dashboard) · 429 — rate limit (120 req/min) or too many jobs in flight · 5xx — transient; retry with backoff.