WideCast.ai

WideCast Documentation

The complete reference for the WideCast.ai public API, SDKs, and integrations.

Looking for a 30-second pitch? Head to the WideCast homepage.

Quickstart

# 1. Create from plain-text script
RESP=$(curl -sS -X POST "https://widecast.ai/app/dashboard2/v1/create_video" \
  -H "Content-Type: application/json" \
  -d '{
    "script_text": "You should let your teen get a driver's license at 16."
  }')
VID=$(echo "$RESP" | jq -r .id)

# 2. Poll until completed
INTERVAL=5
until [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ]; do
  sleep $INTERVAL
  STATUS=$(curl -sS "https://widecast.ai/app/dashboard2/v1/status/$VID")
  STATE=$(echo "$STATUS" | jq -r .status)
  INTERVAL=$(( INTERVAL * 3 / 2 < 60 ? INTERVAL * 3 / 2 : 60 ))
done
echo "Review at: $(echo "$STATUS" | jq -r .result.review_url)"

from widecast import Widecast

client = Widecast(api_key="wc_live_REPLACE_ME")
video = client.create_video(
    script_text="You should let your teen get a driver's license at 16."
).wait()                                      # auto-polls /v1/status with 5s→60s exp backoff
print(video.status, video.review_url)

import Widecast from "@widecast/sdk";

const client = new Widecast({ apiKey: "wc_live_REPLACE_ME" });
const v = await client.create_video({
  script_text: "You should let your teen get a driver's license at 16.",
}).then(v => v.wait());
console.log(v.status, v.review_url);

v0.1.0 endpoints

Endpoint Method Purpose
/v1/create_video POST Submit a finished script (source=text), an idea brief (source=idea), a blog/article (source=blog), or an existing video/audio by URL or upload (source=video_url/video_file/audio_url/audio_file) for AI sourcing
/v1/export_video POST For output_type=scene videos, kick the final-MP4 renderer after review
/v1/edit_session POST (sync, free) Open/close the per-video edit session — start/commit/abort/status. Caches the video in memory so parallel modify_scene writes are conflict-free + reads are instant
/v1/modify_scene POST (sync/async, free) Edit ONE scene — 12 branches: background media, Upload Overlay, Remotion object-layer rect (preferred), group rect, narrator/caption layout, layout.batch, Upload Voice/Narrator Video (async), A/B-roll switch, text, metadata
/v1/scene_geometry POST (sync, free) Data-only scene layout geometry — narrator/caption/Remotion object boxes in 280×498 preview coords, plus collisions + safe zones. Cheap; no screenshot
/v1/scene_inspector POST (sync, free) Expensive last-resort browser inspector — use AFTER /v1/scene_geometry. screenshot_scene_280x498 has a server-fallback composite from thumbnails + overlay poster when no live browser
/v1/upload_asset POST (sync, free) Upload an audio / video / image to WideCast's S3 bucket and get back a 24-hour public URL — use as audio_url / video_url on /v1/create_video
/v1/create_content POST Generate written content — a blog or social post (Facebook/X/LinkedIn) from a URL, idea, or text
/v1/create_image POST Generate 1-4 AI images from a text prompt — returns a numbered thumbnail set for the user to pick (1 credit/image)
/v1/search_broll POST (sync, free) Search stock B-roll — kind=video (Pexels/Pixabay/Shutterstock clips) or kind=image (Google real photos) — returns a numbered thumbnail list
/v1/collect_ideas POST (sync) Video ideas from a product/service description
/v1/publish POST Publish a video / blog / text to connected social platforms (returns request_ids → poll status)
/v1/notification/send POST (sync, free) Push a self-notify notification — email default + Telegram if connected. subject + message (+ optional photo/video URL)
/v1/videos GET (read, free) List the account's recent videos
/v1/video_data POST (sync, free) Read structured scene data (annotated segments, narrator, Remotion spec metadata) — first step for data-first scene audit/edit. Chain: video_data → scene_geometry → modify_scene
/v1/account GET (read, free) Account profile + remaining credits
/v1/analytics GET (read, free) Social analytics dashboard
/v1/roadmap GET (read, free) Content roadmap
/v1/production_plan GET (read, free) Weekly production plan
/v1/foundation_videos GET (read, free) Browse the curated foundation-video template library
/v1/accounts GET (free) List connected social platforms
/v1/platform_settings GET/POST (free) Load / save per-platform publish settings
/v1/status/{id} GET Universal poll endpoint for any async task
Webhooks (out-of-band) Pass callback_url in create_video — WideCast POSTs events to your URL instead of you polling
/openapi.json / /openapi.yaml GET This spec served from the host

Reference

Conventions