Transcript API for video pipelines

How teams wire this

A common path starts with “rag ingestion: chunk text, not raw urls.” Your cron cadence, warehouse schema, and alert thresholds will differ — treat the steps as ordering hints, not a checklist you must copy verbatim.

1. 1

   RAG ingestion: chunk text, not raw URLs

   Pull transcripts from a list of YouTube long-form URLs. Use data.transcript.plainText for embeddings, or data.transcript.segments when you need startMs for citations. TikTok returns WebVTT in data.transcript.content — strip timing cues before your vector store.

2. 2

   TikTok batch with honest fallback policy

   Run two passes or branch in one job: try without useAiFallback first (1 credit) for caption-backed videos. Re-queue failures with useAiFallback=true only when you need text from every clip in the set. Don't blanket-enable AI on 10k URLs — that's 110k credits instead of 10k.

3. 3

   Cross-platform repurposing

   Creator posts the same hook on TikTok and YouTube Shorts. Pull both transcripts, diff the spoken lines, generate a blog draft from the longer YouTube take. One auth header, no platform-specific normalizers in your repo.

4. 4

   Sponsorship and ad-read detection

   Scan YouTube transcripts for 'use code', 'sponsored by', brand names. Timestamps in segments let you jump to the exact moment in the player UI. Pair with /v1/youtube/videos for metadata when you need publish date and view count in the same report.

5. 5

   Instagram Reels in a creator feed

   List recent Reels via /v1/instagram/profiles/{handle}/reels, then transcript each URL. Carousel posts return multiple data.transcripts entries — iterate the array, don't assume a single string.

6. 6

   Accessibility and closed captions

   Ship sidecar captions from timed segments. YouTube's data.transcript.segments gives startMs and endMs per line — enough to generate SRT without parsing anything yourself. TikTok's WebVTT in data.transcript.content works when you already have a VTT renderer.

7. 7

   Handle lookupStatus before you store

   if (data.lookupStatus !== 'found') skip your vector write. not_found still charged. lookup_failed and 503 are free — safe to retry with backoff. Log meta.creditsCharged per row so finance can reconcile batch jobs.

Questions we get from teams shipping transcript pipelines

• Do YouTube and TikTok share a response shape? Yes — data.lookupStatus, data.transcript, meta.creditsCharged. Your parser doesn't fork per platform.
• What if there's no transcript? data.lookupStatus is not_found. You still pay 1 credit — the lookup completed. On TikTok, useAiFallback=true is your escape hatch (+10 credits).
• WebVTT or plain text? TikTok returns WebVTT in data.transcript.content. YouTube gives plainText plus segments with millisecond offsets. Twitter and Facebook return plain strings in data.transcript.
• How do language codes work? Pass language=en (two letters, ISO 639-1). We prefer that track when it exists. No guarantee the creator uploaded in that language.
• Any rate limits? No published cap beyond your credit balance. For big backfills we suggest staying under ~500 concurrent requests — same guidance as our monitoring endpoints.
• Why did my TikTok photo URL fail? Photo carousels aren't videos. You get 400 transcript_target_not_video. Filter non-video URLs before enqueueing if you're watching credit burn.
• Does HTTP 200 mean found? No. Always branch on lookupStatus. We've seen production bugs from teams who assumed 200 = content.
• Instagram carousels? data.transcripts is an array. A 5-slide post can return five entries. Empty array with found status means the post resolved but had nothing to transcribe.
• One API key for everything? Same x-api-key header as profiles, comments, search. Batch YouTube and TikTok in one worker pool without juggling marketplace subscriptions.
• What happens when platforms change? We absorb upstream structure shifts. Your field names stay data.transcript and data.lookupStatus — not whatever HTML class YouTube renamed this week.