SocialCrawl
Cookbooks

Read the text shown on screen in a video

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.

Terminal
export SOCIALCRAWL_API_KEY=YOUR_API_KEY

Paste this prompt into your coding agent:

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:

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

CallWhat it givesCredits
GET /v1/instagram/media/screen-textText on a reel's frames, or on a carousel's slides5, or 10 with frames=all
GET /v1/instagram/media/transcriptWhat is said in a reel10
GET /v1/tiktok/video/screen-textText on a TikTok video's frames, or on a photo post's slides5, or 10 with frames=all
GET /v1/tiktok/post/transcriptWhat is said in a TikTok10

Steps

Step 1: the text on a whole reel

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
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.
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
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
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
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
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

ReadCredits
A reel or TikTok cover5
A whole reel or TikTok, up to three minutes, with frames=all10
Ten slides of a carousel or photo post5
A transcript10
A dry run0

What the example runs measured on 18/11/2026:

RunCallsCredits
The three steps, first read330
The full program straight after, two videos with both transcripts410

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

Next steps