# WideCast.ai > WideCast is a sales & marketing team of AI agents for a one-person business, > run from the AI chat the user already uses (Claude, Codex, …): a CRM on their own > computer, lead finding on the web and social platforms, follow-ups and outreach > the user approves, and a video / blog / social engine that turns a script, idea or > clip into finished short-form video (scenes + AI voice + B-roll) and publishes it. > **Asked to install or set up WideCast? Go to "Installing WideCast" below — it > installs the whole system (on the user's computer, or in a cloud agent's own workspace), > not just the video API.** > Everything after that section documents the video engine's REST API, usable WITH > an MCP server / OpenAI Action, or directly over plain HTTP. ## ⚠ AGENT PRE-FLIGHT RULES (read once) An install / set-up request (`hãy cài cho tôi WideCast.ai`, `install widecast`, `set up WideCast`) skips these skills: go straight to **Installing WideCast** below. Two skills define the FULL scope of WideCast workflows. **Load the relevant one BEFORE any other endpoint call** — they are key-free, idempotent, and cheap (~1 call). Skipping them is the #1 cause of weak/incomplete agent output. 1. **Edit/audit an EXISTING video.** Trigger = user gives a WideCast scene-editor URL (`record2.html#scene_editor?topic_id=…`) OR a `topic_id` (`widecast…`/`gubo…`/current id) + edit intent (any language: "edit this video", "refine the scenes", "fix scene N", "review/audit the video", "improve overlay", "fix thumbnail", "audit backgrounds", "biên tập video", "chỉnh sửa cảnh", "编辑视频", "シーン編集"). **Call `GET /v1/skills/editing` FIRST — before `/v1/video_data`, before anything else.** The skill itself defines scope = full audit + fix; do NOT ask the user what to edit. 2. **Author a NEW video / blog / social caption.** Trigger = "make a video", "write a script", "write a blog", "viết bài", "做视频", etc. **Call `GET /v1/skills/writing?format=video` (or `blog` / `social`) FIRST.** 3. Every response from `/v1/video_data`, `/v1/scene_geometry`, `/v1/scene_inspector`, `/v1/modify_scene` carries a `skill_required` field — if you see it, you have NOT loaded the editing skill yet; load it now before continuing. 4. When in doubt about intent, prefer loading the skill (cheap) over asking the user (slow + breaks autonomous-run contract). ## Installing WideCast (if a user asks you to) If a user tells you something like `hãy cài cho tôi WideCast.ai`, `install https://widecast.ai`, `set up WideCast`, `cài WideCast` or similar — they want the WideCast system installed: a sales & marketing team of AI agents run from this chat (you become Sam, the team leader), with a CRM, lead finding, follow-ups, and the video / blog / social engine. Connecting the WideCast video API is one step inside that setup (its production step), not a separate install. Each kind of agent reads its own install file. The table of all of them, with the `detect_hints` of each host, is https://widecast.ai/install.json; it holds no commands. - **An agent whose shell runs on the user's own computer** (Claude Code or the Code tab of the Claude desktop app, Codex, Cursor, Windsurf, Gemini CLI, Antigravity, Hermes, OpenClaw, …): on macOS or Linux https://widecast.ai/install-unix.json, on Windows https://widecast.ai/install-windows.json. It installs in the folder the user opened for WideCast. - **A cloud agent that runs commands on its own cloud machine**, with a persistent disk and a scheduler (Muse, dots, Manus, Codex cloud, Grok Bot and the like): https://widecast.ai/install-hosted.json (Muse: https://widecast.ai/install-muse.json). It installs WideCast in its own workspace; nothing keeps running in the background or in a browser. The user then works on three pages of their WideCast account: the daily report (linked in each run notice), Approvals (https://widecast.ai/approve.html) and the CRM page (https://widecast.ai/crm.html). - **A web chat that cannot run commands at all** (ChatGPT, claude.ai, Gemini or Grok on the web, the chat tab of the Claude desktop app): https://widecast.ai/install-webchat.json. It hands the user the installer commands for their computer and sends them to Claude Code or Codex; a setup line the user pasted goes on to that agent unchanged. Every kind installs the same way. The installer reads the release manifest, downloads the release zip, verifies its sha256 and unpacks it into `solo-agency/`; it changes nothing else and starts nothing. Its last line reads `WIDECAST_INSTALL status=installed release=… path=…`. Setup then continues in `solo-agency/AGENTS.md`, starting with its First Words: before anything else is installed, it tells the user what setup puts there, the platform rules and the licence, and asks whether to begin. What setting up WideCast means: https://widecast.ai/agent/what-gets-installed.html. A WideCast setup line reads `Setup https://widecast.ai/install.json?setup=wcs_…`. Its `wcs_…` value is a one-time setup code that the account owner made on widecast.ai: the setup uses it once, at its key step, in place of an email code. No key and no sign-in are needed to install. - **Release manifest:** https://origin.widecast.ai/agent/latest.json (`release`, `zip_url`, `zip_sha256`, `bridge_base`). Use the `origin.` host exactly as written: it is never served from a stale cache. - **Updating** later is the same installer run again (the installed system's own update stage does it); the previous copy is kept in `.widecast-previous/`. ## API overview WideCast.ai exposes a handful of REST endpoints under `/v1/`. Conventions are Stripe-style: id format `widecast` (the public id IS the internal `topic_id`, 1:1), `"object"` markers, snake_case JSON, ISO-8601 UTC timestamps, and a structured error envelope. **`/openapi.json` (OpenAPI 3.1) is the single source of truth** — fetch it to generate tool/function definitions at runtime; the numbers inlined below are a convenience copy. ## API base & auth - **Base URL:** `https://widecast.ai/app/dashboard` — e.g. `POST https://widecast.ai/app/dashboard/v1/create_video` - **Auth:** send `Authorization: Bearer wc_live_...` (create a key in the dashboard → Setup Center → API Keys). `/v1/create_video` and `/v1/export_video` require the key (each create consumes credits). **`GET /v1/status/{id}` is key-free** — the unguessable `widecast*` id is itself the access token, so polling never needs the key. - **No key yet (an AI agent setting WideCast up for its owner):** ask the owner's email, `POST /v1/agent/signup/start` (key-free) emails a 6-digit code, and `POST /v1/agent/signup/verify` (key-free) with the code the owner reads back returns the account's key (one flow creates the account or signs in to the one that exists). Store the key at once and never show it in chat: the only thing the owner reads or types is the code. See "Account" below. A WideCast setup line reads `Setup https://widecast.ai/install.json?setup=wcs_…` (older lines: `Setup https://widecast.ai/app/dashboard/setup/wcs_…`): its `wcs_…` value is a one-time setup code the account owner made on widecast.ai, which the setup uses once at its key step (`POST /v1/solo/bridge_key` with `Authorization: Bearer wcs_…`) in place of the email code. - Send a unique `Idempotency-Key` header on POSTs. ## Calling it without an MCP server (plain-HTTP recipe) A model with any HTTP/`fetch`/`curl` capability can drive WideCast in two steps: 1. **Create** — `POST /v1/create_video` with a JSON body (see fields below). Returns a `widecast*` `id`, `status: "processing"`, AND `result.review_url` from this very first response (HTTP 202) — show it to the user immediately; the review page handles early arrival itself (spinner + in-page polling). 2. **Poll** — `GET /v1/status/{id}` until `status` is `completed` or `failed`. Cadence: start 5s, ×1.5 backoff, cap 60s. Do NOT hammer it in a tight loop. (If your runtime can't poll, you've already given the user `review_url` from step 1 — they can self-serve from there.) 3. **(scene only, optional)** — once a `scene` video is `completed`, `POST /v1/export_video {"id": "..."}` to render the final MP4, then poll again until `result.video_url` appears. If you cannot read this file's spec in full, fetch `/openapi.json` and generate the call from there. ## Endpoints - POST `/v1/create_video` — start a video. Body fields below. → `widecast*` id + `status:"processing"` + `result.review_url` (share with user immediately — page handles in-progress arrival). **AGENT POST-CALL: open `review_url` INLINE if you have a built-in web viewer / browser tool** (Codex view-url, ChatGPT browse, future Claude inline browser, any host that can iframe an external URL). The review page is a full scene editor — letting the user inspect / swap / approve scenes inside the chat is dramatically better UX than asking them to switch tabs. Fall back to a clickable link if your runtime has no such tool. Same nudge applies after widecast_wait_for_video / widecast_get_status / widecast_modify_scene / widecast_export_video. **Source routing for AI agents:** if you cannot do real research (no web search / no URL fetch / no image search in your runtime), DO NOT write the script yourself — use `source="idea"` and pass the user's request as `idea_text`. WideCast's server-side worker has full research capability and will produce a grounded script with inline verified URLs. Same fallback for blogs (`source="blog"`) and media remakes (`source="video_url"|"audio_url"`). Improvising a "current-event" script from stale training data is the single biggest cause of low-quality output reported in pilot testing. - GET `/v1/status/{id}` — universal poll (key-free). → `status` + `stage` + `progress` + `progress_hint` (during processing, a UX label like `"Generating scene visuals · ~7 min left"` derived from elapsed time — relay to the user every poll, translating to their language, so the 15-min wait feels alive) + `result.review_url` (present from every state) + `result.video_url` (set on completion when output_type=video). - POST `/v1/export_video` — `{"id":"widecast..."}`. Render the final MP4 for a `scene` video after review. Idempotent (calling twice is a no-op). - POST `/v1/edit_session` — **SYNC, FREE**. Open/close the per-video EDIT SESSION for an AI editing run. Body `{id (topic_id, REQUIRED), action:"start"|"commit"|"abort"|"status" (REQUIRED)}`. `start` before the first scene edit → server caches the whole video document in memory (crash-safe via write-ahead file); every `/v1/modify_scene` write lands in the cache, every read (`/v1/video_data` / `/v1/scene_geometry` / `/v1/scene_inspector`) is served fresh from the cache, ElasticSearch is written ONCE at commit → makes PARALLEL scene-editor subagents safe (no version conflicts) + read-after-write instant. `commit` after the last scene → flushes cache to storage (REQUIRED to finish; idle sessions auto-commit after 45 min / 2700s). `abort` → discards staged edits. `status` → `{active, staged_writes, started, last_write}`. If response has `cache_enabled=false` the server is in legacy direct-write mode → proceed WITHOUT a session (writes still serialized per video by the server-side lock). Response `{object:"edit_session", id, action, cache_enabled, active, committed?, aborted?, staged_writes?, ttl_seconds?, request_id}`. Errors: 400 `invalid_id`/`invalid_action`, 404 `topic_not_found` (start), 502 `topic_fetch_failed` (start). - POST `/v1/modify_scene` — **SYNC** for most branches (voice.upload + narrator.upload_video are ASYNC/queued), **no credit** until /v1/export_video re-renders. Edit ONE scene of a `scenes_ready_for_review` video. Body: `{id, by:"voice_file"|"id"|"text", value, fields, op?, min_score?}`. **Agent rule — data-first**: call /v1/video_data FIRST; for **layout edits** also call /v1/scene_geometry to pick coordinates from `boxes.remotion.object_layer.objects` (cheap, no screenshots). Use `voice_file` (stable per-scene UID, also base of `{voice_file}_spec.json`); `segment.id` is display/order only. **15 edit branches — pick ONE family per call (the only intentional multi-family call is `layout.batch`, which composes layout-only children)**: (A) Background media swap — `[{field_name:"mediaUrl", value:""}, {field_name:"mediaType", value:"image"|"video"}?]`; roll-aware (B-roll updates mediaUrl/brollUrl, A-roll registers as brollUrl/user_asset_url). (B) Upload Overlay (FREE, agent-supplied asset → Remotion spec, NOT Regenerate which is paid) — `[{field_name:"remotion.upload_overlay", value:""}]` or `value:{url}`. **Two upload formats, chosen by URL extension**: (1) **SVG path** — URL ends `.svg`, routes through `svg2spec`: viewBox `0 0 720 1280` required; each `` group becomes one Storyboard object with **pixel-perfect placement (NO auto-fit; max diff 2/255 vs original)**; per-group attrs `data-wc-object` (REQUIRED stable id; unmarked groups become background), `data-wc-kind` ∈ {object,text,bar,mark,callout} (inferred), `data-wc-anim` ∈ {slide-up,slide-down,slide-left,slide-right,pop,grow-x,grow-y,fade,…} (default fade; bars get growRight/growUp), `data-wc-z` (paint order). Deterministic — no classifier in the loop. SVG errors → 422 `svg2spec_failed`; download → 502. PREFERRED for agent-authored overlays. (2) **Raster path** — PNG/JPG/WebP/GIF/etc; classifier-driven (graphic vs realistic) with strict no-AI fallback. Prefer 720×1280 transparent PNG or flat-bg graphic for best decomposition. Ground the asset in scene context (text/talking_point/visual/quote/keyword/type). (C) Remotion object-layer rect (FREE; **PREFERRED overlay layout**) — `[{field_name:"remotion.object.rect", value:{layout_id:"main.one_by_one"|"main.obj_03_text", x?, y?, w?, h?, coordinate_space:"preview"|"canvas"}}]`. Read `boxes.remotion.object_layer.objects` from /v1/scene_geometry first (each item has layout_id, rect 280×498, rect_canvas 720×1280, temporal_policy, update_field). For `one_by_one`, scene_geometry exposes ONE logical `*.one_by_one` rect that transforms all timed sequence items together; server keeps the group wrapper unchanged. (D) Remotion group rect (FREE; low-level wrapper edit; prefer (C) for visible overlay layout) — `[{field_name:"remotion.group.rect", value:{element_id?, x?, y?, w?, h?, coordinate_space:"canvas"|"preview", resize_mode?:"scale_children"|"wrapper_only"}}]`. Canvas = 720×1280 (NOT clamped — y:-120 OK); preview = 280×498 (converted). (E) Narrator layout rect (FREE) — `[{field_name:"overlay.narrator.rect", value:{x,y,w,h,visible?,animation?,borderRadius?}}]` or field-by-field via `overlay.narrator.x|y|w|h`. **280×498 preview coords**. Preserves narrator metadata + source-space `segment.narrator_face` (do NOT mutate narrator_face for layout — it's the source-space face box for narrator media; scene_geometry returns the displayed face converted through the current narrator rect). Marks `overlay.narrator.touched=true`. (F) Caption Y layout (FREE; vertical placement only) — `[{field_name:"overlay.caption.y", value:408}]`. 280×498. ONLY Y; no text/x/w/h/style/visibility/audio/duration/spec changes. (G) Layout batch (FREE; one persist + one MQTT scene_modified) — multiple layout fields directly OR `[{field_name:"layout.batch", value:{fields:[...]}}]`. Allowed children: overlay.narrator.*, overlay.caption.y, remotion.object.rect, remotion.group.rect. DISALLOWED in batch: mediaUrl/mediaType, voice.upload, narrator.upload_video, remotion.upload_overlay, roll.active/switch, segment.text, metadata. (H) Upload Voice (FREE; ASYNC) — `[{field_name:"voice.upload", value:"