Telegen API

The same API the page uses. Sign in on the page with your e-mail address (a code is mailed to it): that makes your account and its API key, shown once. A lost key is replaced with POST /v1/key (or the button on the page): the old one stops working, your episodes and balance stay. JSON in and out; errors are {"error":{"code","message"}}; a 429 has Retry-After.

1. Upload each reference

curl -X POST "https://telegentv.mediaatlas.si/v1/uploads?kind=image&name=rex.png" \
  -H "Authorization: Bearer tg_…" --data-binary @rex.png
→ 201 {"id":"3f9a…","kind":"image","size":183204}

kind is image (png, jpeg, webp, gif; 8 MB), video (mp4, webm; 2–15 s; 40 MB) or audio (wav, mp3, ogg, flac, m4a; up to 15 s; 40 MB). Files not used in an order are deleted after a day.

2. Order the episode

curl -X POST https://telegentv.mediaatlas.si/v1/episodes -H "Authorization: Bearer tg_…" \
  -H "Content-Type: application/json" -d '{
  "brief": "My dog Rex goes to the bakery, buys bread and shares it with a pigeon.",
  "language": "English", "clips": 4,
  "references": [{"upload": "3f9a…", "description": "Rex, my brown labrador"}]}'
→ 202 {"id":"b81c…","state":"waiting_for_telegentv"|"planning"|…}

At most 9 references (3 videos, 3 sounds), each with your description (400 characters). clips is 3 to 5, or leave it out. The director writes the scenes around your words, uses each file only in the clips it belongs in, and does not ask you anything. Refusals are for safety only (real people, minors, sexual content, hate, gore, brands).

3. Look

GET /v1/episodes/b81c…
{"state":"queued","eta_at":1767225600.0,"scenes":4,"done":0,"topic":"Rex buys bread"}
{"state":"done","clips":["/f/…/clip-01.mp4", …],"film":"/f/…/film.mp4"}

state: waiting_for_telegentv, planning, switching_engine, queued, rendering, done, failed. eta_at (epoch seconds) is when the last clip should exist; it is left out when there is no honest estimate. Poll every few seconds at most. Links in clips and film are private and play in a browser.

Writing a brief

The brief is a commission, not a hint: the director writes 3 to 5 clips around it and asks nothing. One idea per episode; say what happens, where and how it ends. Describe every reference as if to someone who cannot see it, and say what must look the same in every clip (each clip is rendered on its own). A sound reference (up to 15 s) is a voice or a noise, a short video (2 to 15 s) is a motion to copy, a picture is a look. One clip can use up to 9 pictures, 3 videos and 3 sounds; an episode takes up to 9 references in all. The page has six ready templates.

{"brief": "Rex, a brown labrador, buys bread at the bakery and shares half with a pigeon. Warm and funny.",
 "language": "English", "clips": 4,
 "references": [{"upload": "…", "description": "Rex, a brown labrador with a red collar and one floppy ear"},
                {"upload": "…", "description": "The bakery: a blue door, bread in the window"}]}

Episodes and payment

Every e-mail address starts with 2 free episodes; an order takes one when it is accepted and gives it back if no clip at all could be made. GET /v1/usage shows episodes_left and the packs. At 0, POST /v1/episodes answers 402 no_episodes_left.

POST /v1/checkout   {"episodes": 5}      (1, 5 or 20: 3, 12, 40 EUR, VAT added at checkout)
{"url":"https://checkout.stripe.com/c/pay/…"}

Packs are sold only while telegentv is running: otherwise 503 telegentv_busy, nothing is charged. You may hold 25 unused episodes. An order reserves one episode and it is used up only when the episode is finished; a failed one is given back. Open the url in a browser and pay by card; the episodes are added within seconds of the payment (Stripe tells us, signed). They do not expire and belong to the e-mail address, so a new key keeps them.

Is it working?

GET /api/status (no key): {"accepting": false, "message": "telegentv is overwhelmed with requests"}. The renderer is a machine that is sometimes off; orders are kept for up to 12 hours and start when it is back.