vid.tv API

Authentication

Two key types, both sent as Authorization: Bearer <key>.

Credits & pricing

New accounts start with 300 credits. Balance: GET /v1/account.

Errors

402 {"error":"Not enough credits ..."}     401 {"error":"missing or invalid api key"}
404 {"error":"agent not found"}            429 {"error":"already hiring - give it a few minutes"}

Every error is JSON with a human-readable error field. 4xx means fix the request; 5xx means try again or contact support@vid.tv.

POST/v1/agents

The front door. Scans the site, writes its brain (summary, hooks, Q&A), casts a host with a matched voice, and queues the seed answer videos - one call.

curl -X POST https://vid.tv/v1/agents   -H "Authorization: Bearer vk_live_..." -H "Content-Type: application/json"   -d '{"website":"https://yoursite.com","seedCount":8,"label":"Homepage","callback_url":"https://yoursite.com/hooks/vidtv"}'

→ { "agentId":"proj_...", "apiKey":"...", "webhookSecret":"whsec_...",
  "brand":"...", "character":{"characterId":"char_...","imageUrl":"..."},
  "seededVideos":[{"videoId":"vid_...","question":"...","status":"queued"}],
  "embed":"<script src=\"https://vid.tv/embed/proj_....js\" async></script>", "brain":{...} }

POST/v1/agents/:id/ask

The visitor runtime - no key needed. Greetings play the welcome clip; known questions return the cached video instantly; close questions fuzzy-match; a genuinely new question gets filmed on the spot.

curl -X POST https://vid.tv/v1/agents/proj_.../ask   -H "Content-Type: application/json" -d '{"question":"do you offer group rates?","sid":"visitor-session-id"}'

→ {"status":"ready","url":"https://vid.tv/media/....mp4","matched":"...","cached":true}
→ {"status":"queued","filming":true,"videoId":"vid_..."}   // new answer being filmed - poll by re-asking
→ {"status":"no_match","leadOffer":true}                  // capped or unowned - offer the lead form

POST/v1/videos

Film a specific answer or a custom script with the agent's host. 8 credits, refunded automatically if the render fails.

-d '{"question":"What are your hours?","script":"We are open seven days...","character_id":"char_..."}'
→ {"videoId":"vid_...","status":"queued","creditsCharged":8}

POST/v1/characters

Recast the host: generate one from a prompt, or upload a face. Voice is auto-matched from the image unless you pass one.

-d '{"prompt":"a cheerful anime travel guide"}'          // generated
-d '{"image_url":"https://.../face.jpg","voice":"Puck (Male)"}'   // your photo, chosen voice

POST/v1/sites

No website yet? Build one. A full AI-designed site for the domain, hosted at a preview URL with a downloadable package.

-d '{"domain":"yourbrand.com","mode":"lite","callback_url":"..."}'
→ {"siteId":"site_...","status":"building"}   // then GET /v1/sites/:id

POST/v1/agents/:id/rescan

Re-read the website and refresh the agent's brain (new pages, new offers). Limited to once per hour per agent.

PATCH/v1/agents/:id

Change label, callback_url, or lead_email (where lead alerts go). Firewalled clients can use POST /v1/agents/:id/update - same body.

POST/v1/leads/:id/handled

Mark a lead done so your team sees what is left. Shows in every leads listing as handled.

POST/v1/agents/:id/audit

The Site Doctor: a professional audit of the agent's site, powered by the live page plus the agent's brain and visitor analytics. Body: {"type": "cro" | "seo" | "pricing"}. Returns a scored report. 15 credits (refunded if the audit fails).

-d '{"type":"cro"}'
→ {"score":6,"summary":"...","findings":[{"issue":"...","impact":"HIGH","evidence":"...","fix":"...","ice":8}]}

DEL/v1/{projects|videos|characters}/:id

Remove an agent (and all its videos), one video, or one character. Firewalled clients: POST .../:id/remove does the same.

GET/v1/roles  ·  /v1/agents/:id/staffing

Every agent is hired for a job, not just a face. Pass role to POST /v1/agents (or PATCH it later) and the role shapes the host's look, its on-camera manner, and what the lead strip asks for.

/v1/agents/:id/staffing reads the site's own pages and returns a hiring plan: which role belongs on which page, and why.

→ {"pagesScanned":11,"plan":[{"path":"/pricing","role":"sales","label":"Sales closer","why":"..."}]}

GET/v1/agents

Everything on your account key: each agent with ready/queued counts and direct URLs for its record, analytics, leads, and hosted page.

GET/v1/agents/:id

The full record: brand, summary, question list, characters, every video with status, the embed snippet, and the hosted page URL.

GET/v1/agents/:id/analytics

The widget tracks automatically - zero setup. Totals, per-day series, top pages, top referrers, top questions, leads captured.

GET/v1/leads  ·  /v1/agents/:id/leads

Account-wide or per-agent. Filters: ?since=ISO&limit=&offset=; add &format=csv for a spreadsheet. Each row: name, email, question, page, kind (followup | subscribe), handled.

GET/v1/agents/:id/questions

Every question visitors asked, tagged exact / fuzzy / greeting / miss. The misses are your content roadmap - film them with POST /v1/videos.

GET/v1/videos/:id

Replicate-style record: input echo, status, url, creditsCharged, timestamps, metrics, and urls{get, web}.

GET/v1/sites/:id  ·  /v1/sites/:id/package.zip

Poll the site build; when done, the preview is live at vid.tv/s/<domain>/ and the zip is the whole deployable site.

GET/v1/account  ·  /v1/characters  ·  /v1/webhook-secret

Balance + usage on the account key; the agent's character reference set; the webhook signing secret (re-fetchable any time).

GET/v1/live?domain=yoursite.com

Open route: which agents are live on a domain - character, ready count, hosted page, and the exact integration code. Powers the on-site admin demos.

HOOKSigned webhooks

Set callback_url and we push instead of you polling. Events: video ready/failed, site done/failed, question.unanswered, lead.captured. Delivery retries at 30s and 120s.

x-vidtv-signature: t=1699999999,v1=hex(HMAC_SHA256(webhookSecret, t + "." + rawBody))

Verify: recompute the HMAC over t + "." + rawBody with your webhook secret and compare to v1.

MAILLead alerts

The moment a visitor leaves their email, the owner (or lead_email) gets it - reply-to is the lead, so replying starts the conversation. Also in the console inbox, the API, and the lead.captured webhook.

MAILWeekly agent report

Once a week the agent writes to you in its own voice: visits, opens, questions answered, what visitors asked that it could not answer, leads captured, and one concrete suggestion.

JSThe embed widget

<script src="https://vid.tv/embed/AGENT_ID.js" async></script>

One line, anywhere before </body>. The bubble loops the welcome video; greetings answer with the intro; cached answers play in milliseconds; new questions film live; the lead strip appears once per visitor. Served fresh from vid.tv on every load - swap the character, add answers, or kill it from our side without touching the page again.

HTMLIframe / hosted page

Every agent has a hosted page at vid.tv/a/AGENT_ID - link it, or iframe it. The frame is CSP-locked to your registered domain, so a copied snippet cannot spend your credits elsewhere.

GET/.well-known/agent.json  ·  /openapi.json

Machine-readable discovery: the agent-network handshake (AgentDAO-compatible) and the full OpenAPI spec.