# headcast

Talking-head videos from a script. You send words, a presenter and a photo; you get a finished mp4.
Base URL: https://staging.headcast.ai
Docs for humans and agents: https://staging.headcast.ai/docs
Every word of those docs in one markdown file: https://staging.headcast.ai/docs.md

## Auth
Every call: `Authorization: Bearer ca_...`. Keys are made by the account owner at /app/api, one at a time.
Accounts are invite-only right now: https://staging.headcast.ai/login#invite

## Price
Plans, each with minutes of finished video a month: Starter $99 for 99 min,
Creator $299 for 340, Pro $699 for 850, Max $1,299 for 1,700
(24% cheaper a minute than Starter). More minutes come as packs of 100, 250 or 500 bought
from the billing page at $1.00 each, the same rate on every plan; bought minutes never expire.
Starter has no API access; every plan above it does. Plan minutes reset monthly. A video is only
accepted when the balance covers its estimate (402 otherwise). Minutes are reserved when a video is
accepted and settled to the real length when it finishes. A failed render costs nothing. Minimum charge one minute.

## Endpoints
GET  /api/v1/me                     account, minutes left, limits
GET  /api/v1/presenters             your presenters, newest first
POST /api/v1/presenters             multipart: name, image, audio -> 202, poll until status is ready
GET  /api/v1/videos                 your last 100 videos
POST /api/v1/videos                 json: script (required), preset, title, setting, callback_url, qr -> 202
POST /api/v1/videos                 multipart: same fields, plus ad_clip + ad_text (your clip over one passage) and qr_image (your own code)
GET  /api/v1/videos/{id}            one video; poll every 10 to 30 seconds
POST /api/ad-slot/match             json: script, passage -> {ok, words, seconds}; check a passage before submitting

## Rules an agent needs
- script: 30 to 6,000 words, plain prose. Markdown, headings, timestamps and beat
  lines are stripped before the words are counted.
- presenter: one front-facing photo of one person, and 8 to 30 seconds of
  them speaking alone. Uploads up to 12 MB. Up to 50 presenters per account.
- status moves queued -> rendering -> done, or failed. Poll; there is no long-polling.
- videos rendering at once depend on the plan (no queue beyond that); read max_inflight from /api/v1/me.
- a video cannot be cancelled once submitted. A failed one can be tried again and it gets a new id.
- callbacks are signed: HMAC-SHA256 hex of the raw body, header X-Cheapavatar-Signature.
- errors are {"error": "sentence"} with a normal HTTP status. Retry 5xx and timeouts, never retry 4xx.
- about 40 minutes for a 10 minute video. The presenter is rendered with HeyGen Avatar IV.
- ad slot: multipart ad_clip (mp4/mov/webm up to 90s and 100 MB, or jpg/png) + ad_text, the
  passage of the script it plays over copied exactly, 6 words or more. Narration keeps running under it.
- qr: {"url" or "source":"upload", "always"|"passage"|"every_min"+"hold_sec", "x", "y", "size_pct"}. x and y are
  fractions of the frame for the code's top-left; size_pct is 5 to 40, default 14.
  "position" (tr/tl/br/bl) still works instead of x/y. Your own code: multipart qr_image, png/jpg/webp under 10 MB.
- the video object carries ad_slot and qr as booleans.