Beta
API

Developers

Send a topic, get back a finished vertical video - script, voiceover, footage, captions and music - for YouTube Shorts, TikTok and Reels. Paid from your credits, like a video made in the app.

1. Get a key

API keys need Silver or higher - from £25 a month. See plans

  1. Make a key below and give it a name. Copy it straight away - it's shown only once.
  2. Send it with every request, as the Authorization header.
  3. Keep it on your server - anyone with the key can spend your credits.

You can have 5 keys at a time, and revoke any of them whenever you like.

Show the example
Authorization: Bearer tc_live_…

The whole API as an OpenAPI 3.1 file, for code generators and AI agents: tallclip.com/openapi.json

2. Make a video

  1. Send a topic to POST /api/v1/videos, with any of the options in the table below.
  2. You get the video's id back at once, while the video is made.
  3. Use that id to check on it (step 3).
Show the example
curl -X POST https://tallclip.com/api/v1/videos \
  -H "Authorization: Bearer $TALLCLIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "Why the Moon is drifting away from Earth", "tone": "Educational", "length": "YouTube Shorts", "visuals": "stock"}'

The answer comes straight back, while the video is made:

HTTP/1.1 202 Accepted
{ "id": "6f1c…", "status": "queued", "credits": 1390, "statusUrl": "/api/v1/videos/6f1c…" }

The whole price is taken when the request is accepted. The voiceover is charged at its most and the difference is given back once the script is written. If the video can't be started, everything is given back; if the render fails, its part is given back automatically.

If the topic asks for something your request won't make as asked - another length, a language TallClip can't speak yet, a drawn look with "visuals": "stock" - the answer also has warnings, each a code and a message to show the person. The video is still made as you sent it.

FieldWhat it is
topicrequiredWhat the video is about, 3 to 300 characters.
toneoptionalDefault "Dramatic". One of: Dramatic, Scary, Funny, Motivational, Mysterious, Educational, Commentator, News report, Documentary, Storyteller, Deadpan, Calm, Advert, How-to, Countdown, Review.
lengthoptionalDefault "YouTube Shorts". One of: Quick (~12s), Instagram Reels (~35s), Snapchat (~50s), YouTube Shorts (~60s), TikTok (~70s), Facebook Reels (~85s), X (~135s), LinkedIn (~175s), Custom / long-form (~180s).
voiceoptionalA voice id - the one the voice picker on the create page uses, e.g. en-US-Chirp3-HD-Charon (the default). Your plan decides which voices you can use.
visualsoptional"stock" (real stock footage, the default) or "photos" (a new AI picture for every shot, Silver and up).
languageoptionalDefault "en". One of: en (English), es (Español), fr (Français), de (Deutsch), it (Italiano), pt (Português), nl (Nederlands), pl (Polski), tr (Türkçe), id (Bahasa Indonesia), sv (Svenska), es-us (Español (Latinoamérica)), fr-ca (Français (Canada)), da (Dansk), nb (Norsk), fi (Suomi), et (Eesti), lv (Latviešu), lt (Lietuvių), cs (Čeština), sk (Slovenčina), sl (Slovenščina), hr (Hrvatski), sr (Српски), bg (Български), ro (Română), hu (Magyar), el (Ελληνικά), ru (Русский), uk (Українська), ar (العربية), he (עברית), ur (اردو), hi (हिन्दी), bn (বাংলা), pa (ਪੰਜਾਬੀ), gu (ગુજરાતી), mr (मराठी), ta (தமிழ்), te (తెలుగు), kn (ಕನ್ನಡ), ml (മലയാളം), sw (Kiswahili), vi (Tiếng Việt), ko (한국어), ja (日本語), zh (中文 (普通话)), yue (粵語), th (ไทย).

Moving AI clips aren't offered through the API yet - make those in the app.

3. Check on it

  1. Ask for the video by its id every 10 to 15 seconds - a one-minute video usually takes a few minutes.
  2. When its status is done, download the MP4 from videoUrl.
Show the example
curl https://tallclip.com/api/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $TALLCLIP_KEY"
{ "id": "6f1c…", "status": "rendering", "progress": 0.42, "stage": "rendering", "credits": 1390, … }
{ "id": "6f1c…", "status": "done", "progress": 1, "videoUrl": "https://…mp4", … }

GET /api/v1/videos?id=VIDEO_ID works too, and GET /api/v1/videos lists your 20 newest.

statusMeans
queuedAccepted, about to start.
writingThe script and voiceover are being made.
renderingWith the video server - progress runs from 0 to 1.
doneFinished. videoUrl is a direct MP4 link that lasts a few hours - ask again for a fresh one. Videos are kept for 30 days.
failedIt couldn't be made; error says why and what was given back.
expiredFinished too long ago - the file has been cleared.

Search the library

Send a few words and get back the pictures and clips that match: every AI picture, moving AI clip and registered creator's upload that may go in anyone's video - the same as the library page (tallclip.com/library). Searching is free.

Show the example
curl "https://tallclip.com/api/v1/library?q=rainy+city+street&type=picture" \
  -H "Authorization: Bearer $TALLCLIP_KEY"
{ "total": 12, "page": 0, "pageSize": 24, "items": [ { "id": "…", "kind": "picture", "title": "…", "bucket": "cleared", "credits": 20, "url": "https://…" }, … ] }

type is all, picture or clip; page runs from 0. Each url is a preview link that lasts six days, and credits is one use in a TallClip video on the lowest plan.

Your account

Ask how many credits you have and which plan you're on.

Show the example
curl https://tallclip.com/api/v1/me -H "Authorization: Bearer $TALLCLIP_KEY"
{ "credits": 120000, "available": 120000, "plan": { "id": "silver", "name": "Silver", "videosPerDay": 1 }, "api": { "allowed": true, … } }

available leaves out credits set aside for scheduled Auto-Pilot posts, which API videos can't spend. In a team, the API spends the team owner's credits, as the app does.

What a video costs

What a video usually costs in credits, with a standard voice - the same figures the app and Auto-Pilot quote. Taken from your plan's credits or any you've topped up. AI pictures cost more on Diamond, which makes them at its top quality.

Credits to pounds: 46,500 credits for £10 at top-up prices, so 1,000 credits is about 22p - a plan's credits work out cheaper. See pricing for plans.

Credits for one video - pounds at top-up prices
LengthStock videoAI pictures (Silver, Gold)AI pictures (Diamond)
Quick (~12s)470 credits (about 10p)760 credits (about 16p)1,180 credits (about 25p)
Instagram Reels (~35s)900 credits (about 19p)1,850 credits (about 40p)3,250 credits (about 70p)
Snapchat (~50s)1,160 credits (about 25p)2,480 credits (about 53p)4,480 credits (about 96p)
YouTube Shorts (~60s)1,350 credits (about 29p)2,990 credits (about 64p)5,340 credits (about £1.15)
TikTok (~70s)1,520 credits (about 33p)3,430 credits (about 74p)6,230 credits (about £1.34)
Facebook Reels (~85s)1,760 credits (about 38p)4,060 credits (about 87p)7,460 credits (about £1.60)
X (~135s)2,720 credits (about 58p)6,420 credits (about £1.38)11,920 credits (about £2.56)
LinkedIn (~175s)3,370 credits (about 72p)8,170 credits (about £1.76)15,170 credits (about £3.26)
Custom / long-form (~180s)3,440 credits (about 74p)8,340 credits (about £1.79)15,490 credits (about £3.33)

A premium voice costs more for the voiceover part: at YouTube Shorts length that part is at most 540 credits on Silver and 1,050 from Gold up, against 320 for a standard voice. When the API accepts a video it takes the voiceover at its most - 1,390 credits in all for a stock video at YouTube Shorts length - and gives back the difference once the script is written, so you end up paying about the figure in the table.

Limits

LimitPer key
New videos20 an hour, 100 a day
All requests (including status checks)1,200 an hour
Videos being written at once5 per account
Keys5 per account

Past a limit you get 429 with a Retry-After header saying how many seconds to wait.

Errors

Every error has the same shape: { "error": { "code": "…", "message": "…" } }. The message is written to be shown to a person.

HTTPcodeWhen
400invalid_requestA field is missing or not one of the allowed values - the message lists them.
401unauthorizedNo key, a mistyped key, or a revoked one.
402insufficient_creditsNot enough credits. Includes balance and needed. Nothing was charged.
403plan_requiredYour plan doesn't include the API (Silver and up).
403plan_blockedYour plan doesn't include that voice or those visuals.
403account_on_holdThe account is on hold after a disputed payment.
404not_foundNo video with that id on this account.
422real_person_not_allowedThe topic asks for something we never make about a real person: sexual or degrading, a fake endorsement, or a made-up claim told as true. May include suggestion, an acceptable version. Nothing was charged.
429rate_limited / too_many_in_flightSlow down - see Limits.
500 / 503server_error / try_againOur side. Nothing was charged for a request that didn't get a 202.

Make a Short from any page

Reading an article you want to turn into a video? Drag this to your bookmarks bar, then click it on any page - TallClip opens with that page ready under From a link. Nothing is charged until you press the button there.

Make a Short (TallClip)← Drag this to your bookmarks bar

Or add a bookmark by hand, with this as its address:

Show the address
javascript:(function(){window.open('https://tallclip.com/create?link='+encodeURIComponent(location.href),'_blank');})();

Chrome extension

The same thing as a button in Chrome's toolbar is on the way. It will only see the page you click it on, and only when you click it. Until then, the bookmark above does the same job.