Data-only scene layout geometry — POST /v1/scene_geometry

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

{
  "id":         "widecast7c0d4f8a9b1e2d3f",
  "voice_file": "XcR0k"
}

{
  "object":          "scene_geometry",
  "id":              "widecast7c0d4f8a9b1e2d3f",
  "topic_id":        "widecast7c0d4f8a9b1e2d3f",
  "company_id":      "<company_id>",
  "scene_id":        3,
  "voice_file":      "XcR0k",
  "score":           1.0,
  "coordinate_space": {
    "width":  280,
    "height": 498,
    "unit":   "editor_preview_px"
  },
  "safe_zones": {
    "dead_top":    { "x": 0, "y": 0,    "w": 280, "h": 49.8,  "coordinate_space": "preview", "reason": "top_10_percent_reserved" },
    "dead_bottom": { "x": 0, "y": 373.5,"w": 280, "h": 124.5, "coordinate_space": "preview", "reason": "bottom_25_percent_reserved" },
    "safe_rect":   { "x": 0, "y": 49.8, "w": 280, "h": 323.7, "coordinate_space": "preview" }
  },
  "scene": {
    "text":           "Meta đã chi 14.3 tỷ đô để mua Scale AI…",
    "talking_point":  "AI training data is the new oil.",
    "type":           "STAT",
    "pattern":        "single_metric",
    "keyword":        "Scale AI",
    "visual":         "Chart of training data spend.",
    "quote":          "$14.3B",
    "show_narrator":  true,
    "active_roll":    "A"
  },
  "boxes": {
    "narrator": {
      "rect":      { "x": 35, "y": 124, "w": 210, "h": 374, "coordinate_space": "preview" },
      "visible":   true,
      "face_source": { "x": 30, "y": 60, "w": 100, "h": 100, "coordinate_space": "narrator_media_280x498" },
      "face":      { "x": 95, "y": 195, "w": 80,  "h": 80,  "coordinate_space": "preview" },
      "face_center": { "x": 135, "y": 235 },
      "face_source_coordinate_space": "narrator_media_280x498",
      "face_coordinate_space_note": "face is converted from face_source through the current overlay.narrator rect"
    },
    "caption": {
      "container_rect":     { "x": 0, "y": 360, "w": 280, "h": 96, "coordinate_space": "preview" },
      "text_rect_estimate": { "x": 10, "y": 370, "w": 260, "h": 60, "coordinate_space": "preview" },
      "visible":            true
    },
    "remotion": {
      "groups": [
        { "id": "main", "rect": { "x": 0, "y": 0, "w": 280, "h": 498 }, "temporal_policy": "simultaneous_static" }
      ],
      "objects": [
        { "id": "obj_01", "rect": { "x": 24, "y": 60,  "w": 232, "h": 42 } },
        { "id": "obj_02", "rect": { "x": 24, "y": 110, "w": 232, "h": 42 } }
      ],
      "object_layer": {
        "objects": [
          {
            "layout_id":       "main.one_by_one",
            "rect":            { "x": 24, "y": 140, "w": 232, "h": 42 },
            "rect_canvas":     { "x": 61.7, "y": 360.5, "w": 596.6, "h": 108.1 },
            "temporal_policy": "one_by_one",
            "update_field":    "remotion.object.rect"
          }
        ]
      },
      "sequence_objects": [
        { "id": "seq_03_text", "start": 0.0, "end": 2.5, "rect": { "x": 24, "y": 140, "w": 232, "h": 42 } }
      ]
    }
  },
  "remotion_spec": {
    "remotion_spec_file":    "XcR0k_spec.json",
    "remotion_spec_url":     "https://widecast.ai/downloads/<company_id>/<topic_id>/XcR0k_spec.json?v=1748293012",
    "remotion_spec_version": "1748293012",
    "remotion_spec_exists":  true,
    "remotion_spec_state":   "ready"
  },
  "summary": {
    "remotion_object_count":             2,
    "remotion_object_layer_count":       1,
    "remotion_sequence_object_count":    1,
    "remotion_group_count":              1,
    "remotion_temporal_policies":        ["simultaneous_static"],
    "remotion_geometry_basis":           "static_poster_objects_with_sequence_metadata"
  },
  "request_id": "req_abcd…"
}

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

{
  "id":                  "widecast7c0d4f8a9b1e2d3f",
  "voice_file":          "XcR0k",
  "include_diagnostics": true
}

{
  /* …default body… */
  "violations": [
    {
      "code":     "remotion_object_in_top_dead_zone",
      "severity": "warning",
      "a":        "remotion.object_layer:main.one_by_one",
      "b":        "dead_zone.top",
      "overlap":  0.18
    }
  ],
  "warnings": [
    {
      "code":     "remotion_object_too_small_for_mobile",
      "severity": "warning",
      "object":   "remotion.object_layer:main.obj_03_text",
      "rect":     { "x": 24, "y": 140, "w": 22, "h": 14 },
      "message":  "Object may be too small to read on mobile."
    }
  ],
  "summary": {
    "error_count":                       0,
    "warning_count":                     2,
    "remotion_object_count":             2,
    "remotion_object_layer_count":       1,
    "remotion_sequence_object_count":    1,
    "remotion_group_count":              1,
    "remotion_temporal_policies":        ["simultaneous_static"],
    "remotion_geometry_basis":           "static_poster_objects_with_sequence_metadata"
  },
  "remotion_spec": {
    /* …same as default, plus: */
    "remotion_poster_file":    "XcR0k_overlay_poster.png",
    "remotion_poster_url":     "https://widecast.ai/downloads/<company_id>/<topic_id>/XcR0k_overlay_poster.png?v=1748293012",
    "remotion_poster_version": "1748293012",
    "remotion_poster_state":   "ready",
    "remotion_poster_exists":  true,
    "remotion_poster_warnings": []
  }
}

from widecast import Widecast

client = Widecast()
geom = client.scene_geometry("widecast7c0d4f8a9b1e2d3f", voice_file="XcR0k")

face = geom["boxes"]["narrator"]["face"]
caption = geom["boxes"]["caption"]["text_rect_estimate"]
print("narrator face:", face)
print("caption text rect:", caption)

# Pick the agent-facing object-layer rect to move
target_obj = next(
    o for o in geom["boxes"]["remotion"]["object_layer"]["objects"]
    if o["layout_id"].endswith(".one_by_one")
)
print("layout_id:", target_obj["layout_id"], "rect:", target_obj["rect"])

# Push the overlay below the face center
new_y = max(int(face["y"]) + int(face["h"]) + 8, 200)
result = client.modify_scene(
    "widecast7c0d4f8a9b1e2d3f",
    by="voice_file", value="XcR0k",
    fields=[
        {"field_name": "remotion.object.rect",
         "value": {"layout_id": target_obj["layout_id"], "y": new_y,
                   "coordinate_space": "preview"}},
    ],
)
print("new spec:", result["remotion_spec_url"])

import Widecast from "@widecast/sdk";

const client = new Widecast();
const geom = await client.scene_geometry("widecast7c0d4f8a9b1e2d3f", {
  voice_file: "XcR0k",
});

const errors = geom.violations.filter((v: any) => v.severity === "error");
if (errors.length > 0) {
  console.log("Layout problems:");
  for (const v of errors) console.log("  ", v.code, "→", v.a, "vs", v.b);
}

curl -sS -X POST ".../v1/scene_geometry" \
  -H "Authorization: Bearer wc_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "id": "widecast7c0d4f8a9b1e2d3f", "voice_file": "XcR0k" }' | jq