Read a video's structured scene data — POST /v1/video_data

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

{ "video_id": "widecastABCDEFGHIJKL" }

// HTTP response envelope — small, fits any MCP runtime.
{
  "object":         "video_data",
  "id":             "widecastABCDEFGHIJKL",
  "topic_id":       "widecastABCDEFGHIJKL",
  "delivery_mode":  "download_url",
  "skill_required": "load_widecast_editing_skill_first",
  "review_url":     "https://widecast.ai/#scene_editor?topic_id=widecastABCDEFGHIJKL",
  "data": {
    "url":         "https://origin.widecast.ai/downloads/<co>/widecastABCDEFGHIJKL/video_data/3f0a8b2c91d4e57f.json?v=1782900123",
    "mime_type":   "application/json",
    "bytes":       182394,
    "expires_at":  "2026-06-30T18:32:03Z",
    "ttl_seconds": 900
  },
  "instructions":   "FETCH THE VIDEO DATA NOW (3-step setup): 1) mkdir -p ./.widecast-video-data && cd ./.widecast-video-data  2) curl -fsSL '<data.url>' -o video_data.json  3) Read('./.widecast-video-data/video_data.json')",
  "next_action":    "fetch_and_read_video_data_json",
  "meta": {
    "delivery_mode":   "download_url",
    "request_id":      "req_abcd…",
    "freshness":       "fresh-per-call (token unique, ?v=mtime cache-bust)",
    "experiment_note": "Flip back with WIDECAST_VIDEO_DATA_DELIVERY_MODE=inline_content."
  },
  "request_id":     "req_abcd…"
}

{
  "object":         "video_data",
  "id":             "widecastABCDEFGHIJKL",
  "topic_id":       "widecastABCDEFGHIJKL",
  "aspect_ratio":   "portrait",
  "title":          "Why your teen should get a driver's license at 16",
  "language":       "English",
  "total_segments": 6,
  "total_duration": 92.4,
  "scene_identity": {
    "stable_scene_id_field": "voice_file",
    "order_field":           "id",
    "notes": [
      "voice_file is the stable per-scene UID.",
      "segment.id is current display/order and may change after reorder/add/delete.",
      "The Remotion spec for a scene is {voice_file}_spec.json."
    ]
  },
  "segments": [
    {
      "id":                       "0",
      "order_id":                 "0",
      "scene_index":              0,
      "voice_file":               "XcR0k",
      "scene_uid":                "XcR0k",
      "type":                     "A-roll",
      "text":                     "You should let your teen get a driver's license at 16.",
      "talking_point":            "Independence is a foundation skill.",
      "visual":                   "Teen holding car keys, soft daylight.",
      "quote":                    "",
      "keyword":                  "license",
      "duration":                 8.2,
      "mediaUrl":                 "https://widecast-assets.s3.us-west-1.amazonaws.com/.../scene01.jpg",
      "mediaType":                "image",
      "thumbnailUrl":             "https://widecast.ai/downloads/.../thumb_01.jpg",
      "videoTrim":                {},
      "overlay": {
        "caption":  { "rect": { "x": 20, "y": 360, "w": 240, "h": 96 } },
        "narrator": { "rect": { "x": 80, "y": 300, "w": 120, "h": 180 } }
      },
      "narrator": {
        "name": "Sarah", "voice_id": "v_clone_42", "face_id": "f_clone_42",
        "audio_url": "...", "video_url": ""
      },
      "remotion_spec":           "XcR0k_spec.json",
      "remotion_spec_file":      "XcR0k_spec.json",
      "remotion_spec_url":       "https://widecast.ai/downloads/<company_id>/widecastABCDEFGHIJKL/XcR0k_spec.json?v=1748293012",
      "remotion_spec_version":   "1748293012",
      "remotion_spec_exists":    true,
      "remotion_spec_state":     "ready",
      "agent_meta": {
        "stable_scene_id_field": "voice_file",
        "stable_scene_id":       "XcR0k",
        "order_field":           "id",
        "order_value":           "0",
        "scene_index":           0,
        "remotion_spec": {
          "file":     "XcR0k_spec.json",
          "url":      "https://widecast.ai/downloads/<company_id>/widecastABCDEFGHIJKL/XcR0k_spec.json?v=1748293012",
          "state":    "ready",
          "exists":   true,
          "version":  "1748293012"
        },
        "coordinate_spaces": {
          "canvas":  { "width": 720, "height": 1280, "used_by": "remotion_spec.*, modify_scene remotion.* fields" },
          "preview": { "width": 280, "height": 498,  "used_by": "overlay.caption, overlay.narrator (legacy)" }
        }
      }
    },
    {
      "id":                       "1",
      "order_id":                 "1",
      "scene_index":              1,
      "voice_file":               "Z9p2m",
      "scene_uid":                "Z9p2m",
      "type":                     "B-roll",
      "text":                     "Here's why responsibility starts behind the wheel.",
      "duration":                 12.7,
      "mediaUrl":                 "https://pexels.com/.../teen_driving.mp4",
      "mediaType":                "video",
      "brollUrl":                 "https://pexels.com/.../teen_driving.mp4",
      "thumbnailUrl":             "https://pexels.com/.../teen_driving_thumb.jpg",
      "remotion_spec":            "none",
      "remotion_spec_file":       "Z9p2m_spec.json",
      "remotion_spec_url":        "",
      "remotion_spec_exists":     false,
      "remotion_spec_state":      "disabled",
      "narrator": {}
    }
  ],
  "global_settings": {
    "aspectRatio":       "portrait",
    "voice_type":        "clone",
    "avatar_type":       "clone",
    "last_voice_type":   "clone",
    "last_avatar_type":  "clone"
  },
  "review_url": "https://widecast.ai/#scene_editor?topic_id=widecastABCDEFGHIJKL",
  "request_id": "req_abcd…"
}

import json
import urllib.request
from widecast import Widecast

client = Widecast()
envelope = client.video_data("widecastABCDEFGHIJKL")

# URL-response mode (default): fetch the published JSON file.
with urllib.request.urlopen(envelope["data"]["url"]) as resp:
    data = json.load(resp)

for seg in data["segments"]:
    print(f"Scene {seg['scene_index']} ({seg['type']}, {seg['duration']:.1f}s)")
    print(f"  voice_file: {seg['voice_file']}")
    print(f"  spec state: {seg['remotion_spec_state']}")
    print(f"  text:       {seg['text'][:80]}")

target = next(s for s in data["segments"] if "license" in (s.get("keyword") or ""))
client.modify_scene(
    data["id"],
    by="voice_file",
    value=target["voice_file"],
    fields=[{"field_name": "mediaUrl", "value": "https://example.com/new.jpg"}],
)

import Widecast from "@widecast/sdk";

const client = new Widecast();
const envelope = await client.video_data("widecastABCDEFGHIJKL");
const data = await (await fetch(envelope.data!.url)).json();
for (const seg of data.segments) {
  console.log(`Scene ${seg.scene_index} ${seg.type} ${seg.duration?.toFixed(1)}s voice_file=${seg.voice_file}`);
}

{ "name": "widecast_video_data", "arguments": { "video_id": "widecastABCDEFGHIJKL" } }
// → envelope contains data.url; agent must:
//     mkdir -p ./.widecast-video-data && cd ./.widecast-video-data
//     curl -fsSL '<data.url>' -o video_data.json
//     Read('./.widecast-video-data/video_data.json')
// → inspect segments; pick voice_file; then call widecast_modify_scene with by="voice_file".