API

What it is

The API is the same one the website uses, opened to keys. Everything the studio can do for your account, it can do for a key: create videos, read their progress, approve the storyboard, pick a thumbnail, upload to your channel. Plan limits, credits, per-video redraw limits and ownership apply exactly as they do on the site.

API keys are on the Creator and Studio plans. Make one under API keys in the studio. The key is shown once; only a fingerprint is kept, so if you lose it, make a new one and revoke the old.

Calling it

Send the key as a bearer token to https://tellavid.com/api. A key can make and read videos; it cannot make or revoke other keys. Each key may make 120 requests a minute.

• Authorization: Bearer tvk_your_key
• Content-Type: application/json for requests with a body
• Errors are JSON, like {"error": "what went wrong"}. A 402 means not enough credits or a plan limit; a 429 means slow down.

Make a video

POST /api/projects with a topic and a format. The studio then writes, narrates, draws and pauses at the storyboard for your review (set autopilot to false to run the steps yourself).

• topic (3 to 500 characters) and niche (a format key such as finance, documentary, top_10 or video_essay; GET /api/themes lists them) are required
• target_minutes: 5, 10, 15, 20, 25 or 30
• optional: visual_style, voice_id, character_id, channel_id, scheduled_for, caption_style, music_mood, extra_instructions
• the answer: {"id": "…", "credits_charged": 10, "autopilot_job_id": "…"}

Many videos at once

POST /api/projects/bulk with {"items": [ … up to 25 of the same objects … ]}. Each video is made as if you had made it alone, one after another. The answer lists which worked and which didn't, so running out of credits part-way through a batch loses nothing already made.

Follow it and finish it

Poll the project until it reaches the review stop, then approve it. After the render it can upload to your linked channel.

• GET /api/projects/:id: status, scenes, the render, the publishing kit
• POST /api/projects/:id/approve: start the render after you've reviewed the storyboard
• POST /api/projects/:id/thumbnail {asset_id}: choose one of the thumbnail options
• POST /api/projects/:id/youtube {channel_id, title_index, publish_at}: upload to your channel on a date
• GET /api/projects: your videos, newest first

An example

curl -X POST https://tellavid.com/api/projects -H "Authorization: Bearer $TELLAVID_KEY" -H "Content-Type: application/json" -d '{"topic": "Why airports put the shops after security", "niche": "business_economics", "target_minutes": 10}'