> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt). ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** --- # Transcript API for video pipelines Spoken text from public YouTube, TikTok, and Instagram Reels — WebVTT or plain text, same data + meta envelope, TikTok AI fallback when captions are missing. Each platform exposes captions differently — WebVTT, empty bodies, carousel slides, mismatched language codes. DIY downloaders mean three parsers and unclear billing on no-track videos. Pass a public URL, read data.transcript, branch on data.lookupStatus. Completed not_found still bills; lookup_failed and 503 do not. ## Endpoints | Method | Path | What it does | | --- | --- | --- | | GET | `/v1/youtube/videos/transcript` | Watch URLs, youtu.be links, Shorts — all normalised. Returns data.transcript.plainText plus timed data.transcript.segments (startMs, endMs per line). Optional language (ISO 639-1, e.g. en) when multiple caption tracks exist. 1 credit per completed lookup. | | GET | `/v1/tiktok/videos/transcript` | vm.tiktok.com short links and /@user/video/… URLs. WebVTT when captions exist. Set useAiFallback=true for speech-to-text when there's no track — the +10 AI surcharge (11 total) applies only when AI produced the transcript. Photo carousels return 400 transcript_target_not_video after charge. | | GET | `/v2/instagram/media/{media}/transcript` | Reels and video posts by shortcode, URL or media id. Returns data.transcript.text; a carousel with several videos returns their texts joined in order. AI transcription with a 120-second cap; longer Reels return video_too_long_for_transcription. 1 credit per completed lookup. | | GET | `/v1/twitter/tweets/transcript` | Video tweets on X. Plain text in data.transcript. Same lookupStatus pattern. Handy when your monitoring pipeline already pulls tweet URLs and you want spoken content without a second vendor. | | GET | `/v1/facebook/posts/transcript` | Reels and video posts on Facebook. Plain text response. Same 120-second AI transcription limit as Instagram. Useful for cross-posted creator content you already track on other networks. | | GET | `/v1/reddit/posts/transcript` | Hosted video on Reddit posts. Optional language param. data.transcript.plainText when found. Niche, but if you're already mining Reddit threads for product research, you don't need a separate path for v.redd.it clips. | ## Workflow 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 for caption tracks (plain text when AI transcribed the audio) — strip timing cues before your vector store. 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. **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. **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. **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. **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. **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. ## TikTok with AI fallback when captions are missing ```bash curl -sS \ -H "x-api-key: YOUR_API_KEY" \ -G "https://api.socialfetch.dev/v1/tiktok/videos/transcript" \ --data-urlencode "url=https://www.tiktok.com/@creator/video/7123456789012345678" \ --data-urlencode "useAiFallback=true" \ --data-urlencode "language=en" ``` ## 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. ## FAQ ### How do I get video transcripts into Claude Code? Connect the hosted MCP server: run `claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp`, then `/mcp` to sign in with OAuth. Your agent can then call the transcript tools directly. If your client cannot complete OAuth, pass your key as an `x-api-key` header instead. Setup details: [MCP docs](https://www.socialfetch.dev/docs/integrations/mcp). ### Is there a full walkthrough for TikTok transcripts? Yes. The [TikTok transcript API guide](https://www.socialfetch.dev/blog/tiktok-transcript-api) covers what the response contains, how many TikToks have caption tracks (from a 74-video sample), AI fallback costs, Python and Node.js code, and a pricing comparison. ### Can one API key cover transcripts and Reddit subreddit posts? Yes. The same `x-api-key` works for `GET /v1/tiktok/videos/transcript` and for Reddit routes such as `GET /v1/reddit/subreddits/{subreddit}/posts`, which lists a subreddit's hot, new or top posts. Each route's credit cost is on its docs page. See the [Reddit data API](https://www.socialfetch.dev/platforms/reddit).