# Screen text (/docs/recipes/on-screen-text) Read the words written on screen in an Instagram reel or a TikTok, second by second, and the voiceover beside them Send a reel or TikTok link and get back the words shown on screen, with the second each one appears. Add the transcript when you also need what is said. The examples use two public NASA videos. Measured on 18/11/2026: the 29-second reel showed 8 lines of text, from "THIS OR THAT" at 0 seconds to an application link at 25. Its voiceover was one short exclamation. The three steps cost 30 credits. ## Start in five minutes Set your key once. Every block on this page reads it. ```bash title="Terminal" export SOCIALCRAWL_API_KEY=YOUR_API_KEY ``` Paste this prompt into your coding agent: ```text title="Prompt" Read https://www.socialcrawl.dev/docs/recipes/on-screen-text.md and follow it to read the on-screen text of https://www.instagram.com/reel/DfpowZdlfMz/. Use the key in SOCIALCRAWL_API_KEY. Price each paid call with a dry run first (add dry_run=1, which is free), and add up the prices. Keep the whole job under max_credits=40: stop and ask me before you go past it. ``` Or price the first call yourself. A dry run validates the request for 0 credits: ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/instagram/media/screen-text" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "url=https://www.instagram.com/reel/DfpowZdlfMz/" \ --data-urlencode "frames=all" \ --data-urlencode "dry_run=1" ``` It answers a hold of 10 credits, settling between 5 and 10. ## How it works - Captions and transcripts miss the words a creator writes on the video itself. - The screen-text call reads those words off the video's frames. On TikTok it also reads the app's own text stickers. - By default it reads the cover. With `frames=all` it reads the whole video, up to three minutes. - The transcript call returns what is said, so you can tell a spoken name from a written one. - You read each post once and keep the answer. ## What you need | Call | What it gives | Credits | | --- | --- | --- | | `GET /v1/instagram/media/screen-text` | Text on a reel's frames, or on a carousel's slides | 5, or 10 with `frames=all` | | `GET /v1/instagram/media/transcript` | What is said in a reel | 10 | | `GET /v1/tiktok/video/screen-text` | Text on a TikTok video's frames, or on a photo post's slides | 5, or 10 with `frames=all` | | `GET /v1/tiktok/post/transcript` | What is said in a TikTok | 10 | ## Steps ### Step 1: the text on a whole reel **cURL** ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/instagram/media/screen-text" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "url=https://www.instagram.com/reel/DfpowZdlfMz/" \ --data-urlencode "frames=all" ``` **Python** ```python title="Python" import json, os, urllib.parse, urllib.request params = {"url": "https://www.instagram.com/reel/DfpowZdlfMz/", "frames": "all"} url = "https://www.socialcrawl.dev/v1/instagram/media/screen-text?" + urllib.parse.urlencode(params) req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}) data = json.load(urllib.request.urlopen(req, timeout=180))["data"] print(data["texts"]) for block in data.get("timeline") or []: print(block["at_seconds"], block["kind"], block["text"]) ``` - `texts` holds every distinct line once, in reading order. - `timeline` gives each line with `at_seconds`, the second it first appears, and `kind`. - `subtitles` holds the on-screen captions of the speech, kept apart from `texts`. ```json title="Response (trimmed)" { "texts": ["THIS OR THAT\nASTRONAUT CANDIDATES", "Earthrise 🌍 Moonrise 🌕"], "timeline": [ { "at_seconds": 0, "kind": "text", "text": "THIS OR THAT\nASTRONAUT CANDIDATES" }, { "at_seconds": 10, "kind": "text", "text": "Earthrise 🌍 Moonrise 🌕" }, { "at_seconds": 25, "kind": "text", "text": "Apply to be\nan astronaut at:\nGO.NASA.GOV/ASTRO2026" } ], "subtitles": [], "duration_seconds": 29.117, "frame": "all" } ``` ### Step 2: what is said in it **cURL** ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/instagram/media/transcript" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "url=https://www.instagram.com/reel/DfpowZdlfMz/" ``` **Python** ```python title="Python" import json, os, urllib.parse, urllib.request params = {"url": "https://www.instagram.com/reel/DfpowZdlfMz/"} url = "https://www.socialcrawl.dev/v1/instagram/media/transcript?" + urllib.parse.urlencode(params) req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}) data = json.load(urllib.request.urlopen(req, timeout=180))["data"] for t in data["transcripts"]: print(t["text"]) ``` - A transcript is kept for 30 days, so asking again in that time is a free cache hit. - On TikTok, `GET /v1/tiktok/post/transcript` does the same job for 10 credits. ### Step 3: the same on TikTok **cURL** ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/tiktok/video/screen-text" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "url=https://www.tiktok.com/@nasa/video/7705995616794561805" \ --data-urlencode "frames=all" ``` **Python** ```python title="Python" import json, os, urllib.parse, urllib.request params = {"url": "https://www.tiktok.com/@nasa/video/7705995616794561805", "frames": "all"} url = "https://www.socialcrawl.dev/v1/tiktok/video/screen-text?" + urllib.parse.urlencode(params) req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}) data = json.load(urllib.request.urlopen(req, timeout=180))["data"] print(data["duration_seconds"], "seconds") for block in data.get("timeline") or []: print(block["at_seconds"], block["kind"], block["text"]) ``` - `native_texts` holds the text from TikTok's own text tool, and `ocr_texts` what was read off the frames. - `source` says which of the two produced the answer. ## What you get back The two examples came back differently. One showed only written text, and the other only captions of its speech. On the reel, every line on screen was written by the creator: 8 lines in `texts`, and no `subtitles`. The voiceover said none of them. On the 61-second TikTok, every line on screen was a caption of the speech. So `texts` came back empty and `subtitles` held 48 lines, such as "THE MEATBALL BETTER" at 31 seconds. ## Store only what is new Key each answer on the post's URL and never read a post twice. When you find posts with a search, store the URLs first, and send the screen-text call only for URLs you have not read. Keep `texts` and `timeline` as they came, and run your own matching (place names, prices, product names) over them later, for free. ## What it costs | Read | Credits | | --- | --- | | A reel or TikTok cover | 5 | | A whole reel or TikTok, up to three minutes, with `frames=all` | 10 | | Ten slides of a carousel or photo post | 5 | | A transcript | 10 | | A dry run | 0 | What the example runs measured on 18/11/2026: | Run | Calls | Credits | | --- | --- | --- | | The three steps, first read | 3 | 30 | | The full program straight after, two videos with both transcripts | 4 | 10 | The second run paid only for the TikTok transcript. The other three reads were cache hits, which are free. ## Tips, and what not to use - A carousel is read 10 slides a call. Send `slide_offset=10` for slides 11 to 20, and keep going while `next_slide_offset` is set. - With `frames=all`, a video longer than three minutes is refused and refunded. Read its cover instead, without `frames`. - When a video cannot be read whole, the cover is read, the call costs 5, and `warnings` says so. - A post with no text on screen answers an empty `texts` list. That is a real answer, not an error. - Do not use a transcript to find a place name shown on screen. Speech and screen can carry different words. ## Full program and agent brief **Full program (Python)** ```python title="Python" # on_screen_text.py: the on-screen text and the voiceover of each video, read once. # Run: SOCIALCRAWL_API_KEY=... python3 on_screen_text.py (Python 3.9+, nothing to install) import json import os import sqlite3 import urllib.parse import urllib.request KEY = os.environ["SOCIALCRAWL_API_KEY"] BASE = "https://www.socialcrawl.dev/v1" VIDEOS = [ "https://www.instagram.com/reel/DfpowZdlfMz/", "https://www.tiktok.com/@nasa/video/7705995616794561805", ] def get(path, **params): url = f"{BASE}/{path}?" + urllib.parse.urlencode(params) req = urllib.request.Request(url, headers={"x-api-key": KEY}) with urllib.request.urlopen(req, timeout=180) as res: body = json.load(res) return body["data"], body.get("credits_used", 0) db = sqlite3.connect("screen_text.db") db.execute("CREATE TABLE IF NOT EXISTS videos (url TEXT PRIMARY KEY, texts TEXT, timeline TEXT, transcript TEXT)") spent = 0 for video in VIDEOS: if db.execute("SELECT 1 FROM videos WHERE url = ?", (video,)).fetchone(): continue # read once, never again tiktok = "tiktok.com" in video screen, c = get("tiktok/video/screen-text" if tiktok else "instagram/media/screen-text", url=video, frames="all") spent += c if tiktok: spoken, c = get("tiktok/post/transcript", url=video) transcript = spoken.get("transcript") or "" else: spoken, c = get("instagram/media/transcript", url=video) transcript = " ".join(t.get("text") or "" for t in spoken.get("transcripts") or []) spent += c db.execute("INSERT INTO videos VALUES (?, ?, ?, ?)", ( video, json.dumps(screen["texts"]), json.dumps(screen.get("timeline") or []), transcript)) db.commit() print(f"\n{video}") for block in screen.get("timeline") or []: if block["kind"] == "text": print(f" {block['at_seconds']:>5}s {block['text']}") print(f" said: {transcript[:120]}") print(f"\n{spent} credits") ``` **Agent brief** ```text title="Agent brief" Goal: the words shown on screen in each video I give you, and what is said in it, read once each. Read https://www.socialcrawl.dev/docs/recipes/on-screen-text.md first. 1. Dry-run each call with dry_run=1 and add up the prices. Stop if the total passes max_credits=40. 2. For an Instagram link, call instagram/media/screen-text with frames=all, then instagram/media/transcript. 3. For a TikTok link, call tiktok/video/screen-text with frames=all, then tiktok/post/transcript. 4. Skip any URL already in screen_text.db. Store texts, timeline and the transcript by URL. 5. Report each video's on-screen lines with the second they appear. ``` ## Next steps - [Video transcription](/docs/recipes/video-transcription-api.md): What is said in a video, on several platforms. - [Instagram](/docs/instagram.md): Every Instagram endpoint, its parameters and its price. - [TikTok](/docs/tiktok.md): Every TikTok endpoint, its parameters and its price.