Live browser inspector — POST /v1/scene_inspector

// request
{
  "id":         "widecast7c0d4f8a9b1e2d3f",
  "action":     "screenshot_scene_280x498",
  "voice_file": "XcR0k"
}

// response (HTTP 200, Content-Type: application/json)
{
  "object":     "scene_inspector_result",
  "status":     "completed",
  "code":       "ok",
  "action":     "screenshot_scene_280x498",
  "topic_id":   "widecast7c0d4f8a9b1e2d3f",
  "company_id": "<company_id>",
  "request_id": "req_…",
  "result": {
    "action":      "screenshot_scene_280x498",
    "scene_id":    3,
    "voice_file":  "XcR0k",
    "scene_index": 2,
    "screenshot": {
      "url":         "https://origin.widecast.ai/downloads/<co>/<topic>/inspector/XcR0k_5f10e9cc0a384e97.jpg?v=1782700000",
      "mime_type":   "image/jpeg",
      "width":       280,
      "height":      498,
      "bytes":       20498,
      "expires_at":  "2026-06-29T13:30:00Z",
      "ttl_seconds": 900
    }
  }
}

# 1) request the screenshot — server publishes a fresh URL
URL=$(curl -sS -X POST ".../v1/scene_inspector" \
  -H "Authorization: Bearer wc_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "id": "widecast7c0d4f8a9b1e2d3f",
        "action": "screenshot_scene_280x498",
        "voice_file": "XcR0k" }' \
  | jq -r .result.screenshot.url)

# 2) fetch the JPEG — no auth header needed, public URL
curl -sS -o scene.jpg "$URL"

# Python SDK
from widecast import Widecast
import requests

client = Widecast()
resp = client.scene_inspector(
    "widecast7c0d4f8a9b1e2d3f",
    "screenshot_scene_280x498",
    voice_file="XcR0k",
)
url = resp["result"]["screenshot"]["url"]
open("scene.jpg", "wb").write(requests.get(url, timeout=10).content)

// JS SDK
import Widecast from "@widecast/sdk";

const client = new Widecast();
const resp = await client.scene_inspector(
  "widecast7c0d4f8a9b1e2d3f",
  "screenshot_scene_280x498",
  { voice_file: "XcR0k" },
);
const url = resp.result?.screenshot?.url as string;
const blob = await (await fetch(url)).blob();

// request
{
  "id":         "widecast7c0d4f8a9b1e2d3f",
  "action":     "overlay_poster",
  "voice_file": "XcR0k"
}

// response (HTTP 200, Content-Type: application/json)
{
  "object":     "scene_inspector_result",
  "status":     "completed",
  "code":       "ok",
  "action":     "overlay_poster",
  "topic_id":   "widecast7c0d4f8a9b1e2d3f",
  "company_id": "<company_id>",
  "request_id": "req_…",
  "result": {
    "action":      "overlay_poster",
    "scene_id":    3,
    "voice_file":  "XcR0k",
    "scene_index": 2,
    "overlay_poster": {
      "url":         "https://origin.widecast.ai/downloads/<co>/<topic>/inspector/XcR0k_poster.jpg?v=1782700123",
      "mime_type":   "image/jpeg",
      "width":       280,
      "height":      498,
      "bytes":       18234,
      "expires_at":  "2026-06-29T13:32:03Z",
      "ttl_seconds": 900
    },
    "review_checklist": "This is the overlay in isolation on solid black — the background image was stripped so you audit the overlay ONLY. Walk all 8 dimensions: 1) Readability … 2) Typos … 3) Grammar … 4) Semantic … 5) Diacritics … 6) Glyph rendering … 7) Numbers/units/symbols … 8) Punctuation …"
  }
}

{
  "object":   "scene_inspector_result",
  "status":   "unavailable",
  "code":     "no_live_editor"     // or "no_active_editor"
}

POST /v1/scene_inspector
Authorization: Bearer wc_live_REPLACE_ME
Content-Type: application/json

{
  "id":         "widecast7c0d4f8a9b1e2d3f",
  "action":     "get_computed_boxes",
  "voice_file": "XcR0k",
  "activate":   true,
  "timeout_ms": 7000
}

{
  "object":   "scene_inspector_result",
  "status":   "completed",
  "code":     "ok",
  "request_id": "req_…",
  "action":   "get_computed_boxes",
  "topic_id": "widecast7c0d4f8a9b1e2d3f",
  "company_id": "<company_id>",
  "selected_browser": { "browser": "chrome", "os": "macOS", "last_seen": "…", "instance_id": "…" },
  "result": {
    "scene_uid": "XcR0k",
    "boxes": [
      { "selector": "[data-scene-id='XcR0k'] .narrator", "x": 80, "y": 300, "w": 120, "h": 180 },
      { "selector": "[data-scene-id='XcR0k'] .caption",  "x": 20, "y": 360, "w": 240, "h": 96 }
    ]
  }
}

{
  "object": "scene_inspector_result",
  "status": "error",
  "code":   "browser_error",
  "result": { "message": "…" }
}

from widecast import Widecast
import requests

client = Widecast()
data = client.video_data("widecast7c0d4f8a9b1e2d3f")
target = data["segments"][2]

resp = client.scene_inspector(
    video_id=data["id"],
    action="screenshot_scene_280x498",
    voice_file=target["voice_file"],
    activate=True,
    timeout_ms=7000,
)

if resp["status"] == "completed" and resp.get("code") == "ok":
    # Success — compositor is the sole screenshot path, so `code: "ok"`
    # covers both "live editor was present" and "server composed from
    # thumbnails + overlay poster". Agent just reads the URL.
    url = resp["result"]["screenshot"]["url"]
    open("scene.jpg", "wb").write(requests.get(url, timeout=10).content)
    print("saved screenshot to scene.jpg")
else:
    # Composition itself failed (rare) — fall back to scene_geometry data
    geom = client.scene_geometry(data["id"], voice_file=target["voice_file"])
    print("falling back to scene_geometry:", geom["summary"])

from widecast import Widecast
import requests

client = Widecast()
resp = client.scene_inspector(
    video_id="widecast7c0d4f8a9b1e2d3f",
    action="overlay_poster",
    voice_file="XcR0k",
)

if resp["status"] == "completed" and resp.get("code") == "ok":
    poster = resp["result"]["overlay_poster"]
    open("overlay.jpg", "wb").write(requests.get(poster["url"], timeout=10).content)
    # Print the reminder so the agent reads it before judging
    print(resp["result"]["review_checklist"])
    # → walks the 8 dimensions: readability / typos / grammar / semantic /
    #   diacritics / glyph rendering / numbers / punctuation
elif resp.get("code") == "overlay_not_available":
    print("Scene has no overlay to audit — upload one first.")

import Widecast from "@widecast/sdk";

const client = new Widecast();
const data = await client.video_data("widecast7c0d4f8a9b1e2d3f");
const target = data.segments[2];

// For structural boxes, prefer scene_geometry — no browser needed.
const geom = await client.scene_geometry(data.id, { voice_file: target.voice_file });
console.log("narrator face:", geom.boxes.narrator.face);
console.log("violations:", geom.violations);

// Use scene_inspector only when you need browser truth.
const resp = await client.scene_inspector(data.id, "get_preview_state", {
  voice_file: target.voice_file,
});
if (resp.status === "completed") console.log("preview state:", resp.result);

{
  "name": "widecast_scene_inspector",
  "arguments": {
    "video_id":   "widecast7c0d4f8a9b1e2d3f",
    "action":     "list_live_editors"
  }
}