Video transcription pipeline
Pull YouTube, TikTok, and Instagram transcripts with one worker — credit rules, lookupStatus, and SDK examples
Pull transcripts from YouTube, TikTok, and Instagram video URLs. Three routes, one auth header. Response shapes differ — normalize in your app.
You'll need an API key and the TypeScript SDK. MCP tools map 1:1 to these routes after OAuth.
Credit budget
What this costs
YouTube and Instagram transcripts are typically 1 credit per completed lookup. TikTok is 1 credit, or up to 11 when useAiFallback=true (base +10). Completed not_found attempts still bill. lookup_failed / 503 do not.
Pre-check with GET /v1/balance before large batches.
Routes
| Platform | Route | SDK | Notes |
|---|---|---|---|
| YouTube | GET /v1/youtube/videos/transcript | client.youtube.getVideoTranscript({ url, language? }) | segments + plainText; video can be found with transcript: null |
| TikTok | GET /v1/tiktok/videos/transcript | client.tiktok.getVideoTranscript({ url, language?, useAiFallback? }) | WebVTT in transcript.content |
GET /v2/instagram/media/{media}/transcript | client.instagram.getMediaTranscriptV2({ media }) | Plain text in transcript (media is a shortcode, URL or media id) |
Also available when you need them: Twitter tweet transcript (video tweets, ~2 min max), Facebook post transcript, Reddit post transcript, LinkedIn post transcript.
Worker sketch
import { SocialFetchClient } from "@socialfetch/sdk";
const client = new SocialFetchClient({
apiKey: process.env.SOCIALFETCH_API_KEY!,
});
type Platform = "youtube" | "tiktok" | "instagram";
function detectPlatform(url: string): Platform | null {
if (url.includes("youtube.com") || url.includes("youtu.be")) return "youtube";
if (url.includes("tiktok.com")) return "tiktok";
if (url.includes("instagram.com")) return "instagram";
return null;
}
async function transcribe(url: string, useAiFallback = false) {
const platform = detectPlatform(url);
if (!platform) throw new Error("unsupported_url");
const result =
platform === "youtube"
? await client.youtube.getVideoTranscript({ url })
: platform === "tiktok"
? await client.tiktok.getVideoTranscript({ url, useAiFallback })
: await client.instagram.getMediaTranscriptV2({ media: url });
if (!result.ok) {
return { ok: false as const, error: result.error };
}
const { data, meta } = result.value;
return {
ok: true as const,
platform,
lookupStatus: data.lookupStatus,
creditsCharged: meta.creditsCharged,
requestId: meta.requestId,
data,
};
}TikTok useAiFallback adds its 10-credit surcharge only when AI transcribes the audio; captioned videos still cost 1 credit. Leave it off if you only want existing captions. AI covers videos up to 2 minutes unless you also pass allowLongTranscription=true (10 credits per started minute).
Normalize for RAG
Store plain text for embeddings. Keep timed segments / WebVTT if you need clip boundaries. Chunk with overlap; attach url, platform, and language as metadata.
Deep dive: How to get YouTube, TikTok & Instagram transcripts.