Create a video — POST /v1/create_video + GET /v1/status/{id}

Turn a plain-text script, a short idea, a blog/article, or an existing video/audio (by URL or upload) into AI-generated scenes + audio. The pilot exposes three endpoints that work together:

1. POST /v1/create_video — submit script_text (source=text, default), idea_text (source=idea), blog_text (source=blog), or a media URL / file (source=video_url|video_file|audio_url|audio_file). Returns a widecast* id and initial status: "processing". For files attached in chat by AI agents, upload them first via POST /v1/upload_asset and pass the returned URL here.
2. GET /v1/status/{id} — poll until status is completed (or failed).
3. POST /v1/export_video — for output_type=scene videos, kick the final-MP4 renderer after review. See export-video.md.

Pick a source — what kind of input?

For files the AI agent received in chat (audio voice memos / short video clips / reference images), upload via POST /v1/upload_asset (or the MCP widecast_upload_asset tool) first — the response carries a 24-hour S3 URL. Pass that URL here as audio_url / video_url, or use it as an inline ![](url) in script_text.

idea and blog are generative sources: the server runs ai_enhance_script (input → narration) and then continues into the same scene-sourcing pipeline as source=text.

video_* and audio_* are media-ingest sources (the script already lives inside the media): the server downloads (URL) or saves (upload) the file under /mnt/efs/transcoder, then runs the existing footage / audio pipeline. For these, output_type="text" = Remake (extract the spoken transcript only → editable script); scene/video build the full video. language / video_length / research_enabled do not apply (the media dictates the script).

Pick an output_type — how far down the pipeline (pipeline depth)

The two axes combine — every valid source × output_type pair works, except source=text + output_type=text (rejected — you already supplied the script).

When status == "completed": - result.review_url is the URL where the user reviews the result. The UI auto-detects the data state: for output_type=text it opens the Script Editor (narration only, no scenes yet); for output_type=scene it opens the Scene Editor (scenes + audio). Append &readonly=true for a public, sign-in-free, iframe-embeddable read-only player (e.g. …?topic_id=<id>&readonly=true) — embed that variant to show the result inline (in a chat/artifact); the plain URL opens the editor for a signed-in user. - result.video_url is the direct MP4 URL — present only for output_type=video (or after a successful /v1/export_video).

Why text is invalid only for source=text: output_type is pipeline depth. text means "stop after the source→script-text phase". That phase exists for every source EXCEPT text — generative sources (idea/blog) generate the script, media sources (video/audio) extract it. For source=text the caller already provided the script, so text output would just echo the input.

faceless — all-B-roll (no narrator)

By default scenes mix A-roll (narrator) and B-roll (stock video / AI image). Set faceless: true to make every scene B-roll with no narrator anywhere — a "faceless" video. It's orthogonal to output_type (controls A/B-roll, not pipeline depth) and valid with output_type scene/video for the script-based sources (text/idea/blog) AND for source=audio_url — the script lives in the user's audio but the visuals must still be generated, so the same toggle applies. Combining it with output_type=text (no scenes) or a video source (video_url/video_file — the footage IS the visuals) returns invalid_faceless (400). Default false leaves the normal A/B mix unchanged.

Field bounds (LOCKED — A38 parity)

Used VERBATIM by the narrator (source=text) or interpreted by the AI (source=idea / blog). All bounds are LOCKED — the SDKs export them as named constants you should refer to programmatically.

Word count = whitespace split (len(text.split())) — works for English + Vietnamese. Media sources have no word bound — instead a 5-minute duration cap (media_too_long, all media incl. URLs) and, for uploaded files only, a 100 MB size cap (file_too_large). SDKs export MEDIA_MAX_DURATION_SECONDS (300) / MEDIA_MAX_FILE_BYTES (100 MB); file size is pre-validated client-side, duration is server-enforced.

Inline images & video in your script (source=text)

Want a specific shot to appear at a specific moment? Drop a direct image or video URL straight into script_text, right after (or before) the sentence it should illustrate, in either of two equivalent forms. WideCast:

1. strips both forms from the spoken narration (the narrator never reads them aloud), and
2. uses that image/video as the visual for the matching scene, instead of the auto-sourced B-roll it would otherwise pick.

Recommended — markdown image syntax ![alt](url) (chat hosts like Claude / ChatGPT / Grok / Gemini render the picture inline next to the narration, so the end-user can visually approve each scene before the script is submitted; the alt text doubles as the strongest scene anchor):

{
  "source": "text",
  "script_text": "Our new espresso machine pulls a perfect shot every time. ![Stainless-steel espresso machine](https://cdn.example.com/machine.jpg) The secret is precise temperature control, which you can see in action here. ![Slow extraction in close-up](https://cdn.example.com/brewing.mp4) Order yours today at example.com."
}

Backward-compat — raw URL on its own line (still works, no chat preview):

{
  "source": "text",
  "script_text": "Our new espresso machine pulls a perfect shot every time. https://cdn.example.com/machine.jpg The secret is precise temperature control, which you can see in action here. https://cdn.example.com/brewing.mp4 Order yours today at example.com."
}

You can mix forms freely in the same script.

• Supported — direct file links ending in an image extension (.png .jpg .jpeg .gif .webp .bmp .avif .svg) or a video extension (.mp4 .webm .mov .m4v .avi), optionally with a ?query string.
• Not supported as inline assets — page links such as https://youtube.com/watch?v=… or a TikTok URL (they have no media extension). To turn a whole clip into a video, use source=video_url / audio_url instead. For files the AI agent received in chat, upload them via POST /v1/upload_asset and reuse the returned URL.
• Matching — for markdown form, the alt text IS the anchor (model-provided scene description). For raw URLs, WideCast uses the ~6 words on either side. Type (image vs video) is auto-detected from the extension.
• Multiple URLs are fine; scenes without a URL still get automatic B-roll.

This only applies to source=text (your verbatim script). For idea/blog the script is AI-written, and for media sources the visuals come from the clip itself.

Enums (LOCKED v0.1.0)

Convention (A38): every field constraint surfaces in 5 places — this docs page, the OpenAPI spec, SDK constants/types, the playground UI, and server enforcement (with a LOCKED error.code). See HANDOFF §6 (A38) before adding a new field.

POST /v1/create_video

source=text (default — backward-compat):

POST /v1/create_video
Authorization: Bearer wc_live_REPLACE_ME   # required when key enforcement is on (401 otherwise)
Content-Type: application/json
Idempotency-Key: <uuid>                    # optional; read but not enforced in pilot

{
  "source":          "text",                      // optional, default "text"
  "script_text":     "Paste your script here (80–500 words).",
  "output_type":     "scene",                     // optional, "scene" (default) or "video"
  "wait_for_render": false,                       // optional, default false
  "callback_url":    "https://...",               // optional (HMAC-SHA256-signed webhook)
  "metadata":        { "external_id": "..." }     // optional, echoed back
}

source=idea:

POST /v1/create_video
{
  "source":           "idea",
  "idea_text":        "Describe what the video should be about (5–1000 words; longer auto-truncated).",
  "language":         "English",                   // optional, default "English"; English|Vietnamese
  "video_length":     "short",                     // optional, default "short"; short|normal
  "research_enabled": true,                        // optional, default true
  "output_type":      "scene",                     // optional, default "scene"
  "wait_for_render":  false,
  "callback_url":     "https://...",
  "metadata":         {}
}

source=blog:

POST /v1/create_video
{
  "source":           "blog",
  "blog_text":        "Paste your blog post or article here (30–3000 words; longer auto-truncated).",
  "language":         "English",                   // optional, default "English"; English|Vietnamese
  "video_length":     "short",                     // optional, default "short"; short|normal
  "research_enabled": true,                        // optional, default true
  "output_type":      "text",                      // optional, default "scene"; "text" stops at the editable script
  "wait_for_render":  false,
  "callback_url":     "https://...",
  "metadata":         {}
}

source=video_url / audio_url (media by URL — pure JSON):

POST /v1/create_video
{
  "source":      "video_url",                   // or "audio_url"
  "video_url":   "https://www.youtube.com/watch?v=...",   // or "audio_url": "..."
  "output_type": "scene",                        // "text" = Remake (transcript only) | "scene" | "video"
  "callback_url":"https://...",
  "metadata":    {}
}

source=video_file / audio_file (upload — multipart/form-data, mirrors the UI):

curl -X POST ".../v1/create_video" \
  -H "Authorization: Bearer wc_live_REPLACE_ME" \
  -F "source=video_file" \
  -F "output_type=scene" \
  -F "video_file=@/path/to/clip.mp4"        # or -F "audio_file=@ep.mp3" with source=audio_file

The SDKs wrap this: client.create_video(source="video_file", video_file=open("clip.mp4","rb")) (Python) / client.create_video({ source: "video_file", video_file: blob }) (TS).

AI agents — uploading a file attached in chat: call POST /v1/upload_asset (or the MCP widecast_upload_asset tool) first. The response carries a public S3 URL (24-hour TTL); pass that URL here as audio_url / video_url, or use it as an inline ![](url) in script_text. The widecast-assets bucket is the canonical upload path — no need to base64 anything or shop for a third-party host.

Field reference

Response — 202 Accepted (default async path)

{
  "object":   "status",
  "id":       "widecast7c0d4f8a9b1e2d3f",
  "type":     "video",
  "status":   "processing",
  "stage":    "queued",
  "progress":  0.05,
  "result":    null,
  "error":     null,
  "callback_url": null,
  "metadata":  { "external_id": "..." },
  "usage":     null,
  "links":    { "self": "/v1/status/widecast7c0d4f8a9b1e2d3f" },
  "meta":     { "request_id": "req_...", "widecast_version": "0.1.0" }
}

GET /v1/status/{id}

Universal status poll. v0.1.0 supports only the widecast* ids returned by /v1/create_video.

GET /v1/status/widecast7c0d4f8a9b1e2d3f
Authorization: Bearer wc_live_REPLACE_ME

Response (completed — output_type: scene)

{
  "object":   "status",
  "id":       "widecast7c0d4f8a9b1e2d3f",
  "topic_id": "widecast7c0d4f8a9b1e2d3f",
  "type":     "video",
  "status":   "completed",
  "stage":    "scenes_ready_for_review",
  "progress": 1.0,
  "details": {
    "step":       5,
    "status":     "Completed",
    "notes":      "",
    "updated_at": "2026-05-20T12:34:56Z"
  },
  "result": {
    "review_url": "https://widecast.ai/#scene_editor?topic_id=widecast7c0d4f8a9b1e2d3f"
  },
  "error":         null,
  "metadata":      {},
  "usage":         null,
  "links":        { "self": "/v1/status/widecast7c0d4f8a9b1e2d3f" },
  "meta":         { "request_id": "req_...", "widecast_version": "0.1.0" }
}

Response (completed — output_type: video)

{
  "object":   "status",
  "id":       "widecast7c0d4f8a9b1e2d3f",
  "type":     "video",
  "status":   "completed",
  "stage":    "video_rendered",
  "progress": 1.0,
  "result": {
    "review_url": "https://widecast.ai/#scene_editor?topic_id=widecast7c0d4f8a9b1e2d3f",
    "video_url":  "https://widecast.ai/exports/huubinhnguyen/widecast7c0d4f8a9b1e2d3f/final.mp4"
  },
  ...
}

For output_type=video, the completion gate moves from "scenes ready" to "final MP4 rendered" — clients see stage cycle through step_0 → scenes_ready_for_review → rendering_video → video_rendered. The terminal video.completed webhook fires only when the MP4 is ready.

result is intentionally minimal — only the user-facing review_url (+ video_url when applicable). The rendered video script (with segments[]) is NOT inlined to keep status responses cheap. A future GET /v1/videos/{id}/script endpoint will serve it explicitly when needed.

details — raw worker state (⚠ name clash inside)

For fine-grained progress visibility, every status response (except pending race window) includes a details sub-object surfacing the raw legacy worker fields:

During the pending race window (no topic row yet), details is null.

Response (failed)

{
  "status":  "failed",
  "stage":   "step_3",
  "progress": 0.84,
  "result":   null,
  "error": {
    "code":    "credit_exhausted",
    "message": "You don't have enough credits to use this feature. Please consider upgrading your package."
  },
  ...
}

Status enum (LOCKED)

The server mirrors the legacy /checkProgress logic — it queries both video_queue_table (which has progressive step/status updates from the render pipeline) and topics_table (which holds the final scenes-ready state). The richer of the two drives details; the topic-row state drives completion gating.

Progress mapping

Error codes (LOCKED, v0.1.0)

Worker-detected (surface in result.error.code when status === "failed")

Request-validation + auth (surface as HTTP 400 / 401 / 409 error envelope)

error.message echoes the legacy notes verbatim so users see the same wording across surfaces.

Polling cadence (recommended)

Fixed 5 seconds. The SDKs' video.wait() defaults to a constant 5s interval (no exponential backoff). If you want backoff for very long polls, override max_interval / backoff_multiplier on wait().

Try it

The playground submits your script text, then auto-polls /v1/status/{id} until the video is completed (or failed), then renders the review URL.

SDK examples

Four canonical flows, one method per language. The matrix is source × output_type — each combination is a valid call.

Python

from widecast import Widecast

client = Widecast()  # reads WIDECAST_API_KEY env var

# (1) Script → scenes (review-first)  — default
video = client.create_video(
    script_text=open("my_script.txt").read(),   # 80–500 words
).wait()
print("Review at:", video.review_url)

# (2) Script → full MP4
video = client.create_video(
    script_text=open("my_script.txt").read(),
    output_type="video",
).wait(timeout=900)
print("MP4:", video.video_url)

# (3) Idea → scenes (AI writes the script first)
video = client.create_video(
    source="idea",
    idea_text="Why teens should get their driver's license at 16, not 18.",
    language="English",                  # default
    video_length="short",                # default ~90s
).wait(timeout=900)
print("Review at:", video.review_url)

# (4) Idea → full MP4 (Spanish narration, longer) — language="Spanish"
# tells WideCast to write the narration in Spanish even if the brief is in English.
video = client.create_video(
    source="idea",
    idea_text="Why parents should let their teen learn to drive at 16.",
    language="Spanish",
    video_length="normal",               # cap ~3 min
    research_enabled=True,               # default — explicit for clarity
    output_type="video",
).wait(timeout=900)
print("MP4:", video.video_url)

TypeScript

import Widecast from "@widecast/sdk";

const client = new Widecast();

// (1) Script → scenes
let v = await client.create_video({ script_text: scriptText }).then(v => v.wait());
console.log("Review:", v.review_url);

// (2) Script → MP4
v = await client.create_video({
  script_text: scriptText,
  output_type: "video",
}).then(v => v.wait({ timeoutMs: 900_000 }));
console.log("MP4:", v.video_url);

// (3) Idea → scenes
v = await client.create_video({
  source: "idea",
  idea_text: "Why teens should get their license at 16, not 18.",
}).then(v => v.wait({ timeoutMs: 900_000 }));
console.log("Review:", v.review_url);

// (4) Idea → MP4 (Spanish narration, normal length)
v = await client.create_video({
  source: "idea",
  idea_text: "Why parents should let their teen learn to drive at 16.",
  language: "Spanish",
  video_length: "normal",
  output_type: "video",
}).then(v => v.wait({ timeoutMs: 900_000 }));
console.log("MP4:", v.video_url);

Detecting auto-truncation (generative sources over their ceiling)

If you submit an over-long generative input (idea_text > 1000 words, or blog_text > 3000 words), the server trims it at the ceiling. The original count surfaces on /v1/status under one shared key, details.input_truncated_from (regardless of source):

status = client.get_status(video_id)
if status.details and status.details.get("input_truncated_from"):
    print(f"Server trimmed your {status.details['input_truncated_from']}-word input.")

Manual polling (curl)

VID=$(curl -sS -X POST ".../v1/create_video" \
  -H "Content-Type: application/json" \
  -d '{"script_text":"You should let your teen get a driver'"'"'s license at 16."}' \
  | jq -r .id)

INTERVAL=5
until [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ]; do
  sleep $INTERVAL
  RESP=$(curl -sS ".../v1/status/$VID")
  STATE=$(echo "$RESP" | jq -r .status)
  INTERVAL=$(( INTERVAL * 3 / 2 < 60 ? INTERVAL * 3 / 2 : 60 ))
done
echo "Review: $(echo "$RESP" | jq -r .result.review_url)"

Top-level errors (request-level)

Every error response includes error.request_id — include it in any support ticket.