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
- Make a key below and give it a name. Copy it straight away - it's shown only once.
- Send it with every request, as the Authorization header.
- 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
- Send a topic to
POST /api/v1/videos, with any of the options in the table below. - You get the video's id back at once, while the video is made.
- 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.
| Field | What it is | |
|---|---|---|
topic | required | What the video is about, 3 to 300 characters. |
tone | optional | Default "Dramatic". One of: Dramatic, Scary, Funny, Motivational, Mysterious, Educational, Commentator, News report, Documentary, Storyteller, Deadpan, Calm, Advert, How-to, Countdown, Review. |
length | optional | Default "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). |
voice | optional | A 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. |
visuals | optional | "stock" (real stock footage, the default) or "photos" (a new AI picture for every shot, Silver and up). |
language | optional | Default "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
- Ask for the video by its id every 10 to 15 seconds - a one-minute video usually takes a few minutes.
- When its status is
done, download the MP4 fromvideoUrl.
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.
| status | Means |
|---|---|
| queued | Accepted, about to start. |
| writing | The script and voiceover are being made. |
| rendering | With the video server - progress runs from 0 to 1. |
| done | Finished. videoUrl is a direct MP4 link that lasts a few hours - ask again for a fresh one. Videos are kept for 30 days. |
| failed | It couldn't be made; error says why and what was given back. |
| expired | Finished 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.
| Length | Stock video | AI 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
| Limit | Per key |
|---|---|
| New videos | 20 an hour, 100 a day |
| All requests (including status checks) | 1,200 an hour |
| Videos being written at once | 5 per account |
| Keys | 5 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.
| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | A field is missing or not one of the allowed values - the message lists them. |
| 401 | unauthorized | No key, a mistyped key, or a revoked one. |
| 402 | insufficient_credits | Not enough credits. Includes balance and needed. Nothing was charged. |
| 403 | plan_required | Your plan doesn't include the API (Silver and up). |
| 403 | plan_blocked | Your plan doesn't include that voice or those visuals. |
| 403 | account_on_hold | The account is on hold after a disputed payment. |
| 404 | not_found | No video with that id on this account. |
| 422 | real_person_not_allowed | The 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. |
| 429 | rate_limited / too_many_in_flight | Slow down - see Limits. |
| 500 / 503 | server_error / try_again | Our 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.
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.