Transcript API for video pipelines

How teams wire this

Typical order starts with “rag ingestion: chunk text, not raw urls.” Adjust cadence, schema, and thresholds to your stack.

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: one pass with AI fallback on

   With useAiFallback=true, captioned videos still cost 1 credit and only the clips AI actually transcribes cost 11, so one pass is fine. Leave it off if you only want creator or auto captions. AI covers clips up to 2 minutes; add allowLongTranscription=true for longer ones (10 credits per started minute).

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 /v2/instagram/profiles/{profile}/media?tab=reels, then transcript each one. A carousel with several videos returns their texts joined in order in a single data.transcript.text.

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, only when AI returns text).
• 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 request quotas on paid metered routes — credits are the only limit. Concurrency is capped at 200 requests in flight per workspace; over that, or under extreme load, you get 503 with Retry-After (not charged).
• 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? A carousel with several videos returns their texts joined in order in data.transcript.text. A video with no speech is found with transcript.text set to null.
• 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 structure shifts. Your field names stay data.transcript and data.lookupStatus — not whatever HTML class YouTube renamed this week.