Stories and revisions

A story combines ready footage assets with reporter copy and requested variants. Preparation returns an asynchronous job with job.story.id immediately. The completed result is an immutable revision containing captions, exact copy spans, source cuts, crop choices and checks. Preparing a draft never starts a render or publishes anything.

Prepare a package

Upload your own footage first and wait for every asset to be ready. Then create the story:

curl https://api.story0.com/v1/stories \
  -H "Authorization: Bearer $STORY0_API_KEY" \
  -H "Idempotency-Key: story-order-42" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"asset_id":"asset_first"},{"asset_id":"asset_second"}],
    "article": {
      "headline":"Community restores a neighborhood garden",
      "body":"Volunteers restored a neighborhood garden on Saturday. The work included clearing paths and planting flowers."
    },
    "variants": [
      {"id":"en-landscape","kind":"captioned","language":"en-US","aspect":"16:9"},
      {"id":"de-portrait","kind":"captioned","language":"de-DE","aspect":"9:16"},
      {"id":"clean","kind":"clean","aspect":"16:9"}
    ],
    "audio":{"mode":"mute"},
    "billing":{"max_charge":{"currency":"USD","amount":"3.00"}}
  }'

Poll GET /v1/jobs/{id}?wait=5, or consume job.succeeded. The job's result.url retrieves the revision. GET /v1/stories/{id} gives the current revision pointer; GET /v1/stories/{id}/revisions pages through history.

The neutral style contains no customer brand, channel rules, logo or automatically chosen music. Configure inline style values for caption color and sizes, alignment, reading speed, maximum duration, pacing and framing. The complete style is frozen in each revision, with a config_hash. framing: "fit" preserves the source inside the requested canvas; subject_crop enables planned crop framing.

Grounding and timing

• copy_text is the headline, a newline, and article body. source_spans use UTF-16 code-unit offsets into that string, matching JavaScript string slicing. Python callers should convert code units when the copy contains characters outside the BMP, such as emoji.
• Facts retain exact quotations from the supplied copy. Captions link to facts and visual source evidence. Numeric and quotation checks help surface unsupported statements; automated checks are not verification that the reporter copy is true.
• Each language is authored from the copy independently. It is not silently translated from a single master caption script.
• Clip source_start and source_end refer to the input asset. Clip start and end refer to the output composition. These are separate clocks, in seconds.
• Each variant includes checks. Errors block approval. Warnings require explicit acknowledgement when approving the exact preview.

Story preparation uses a richer source log for speech, credits and framing. It reuses that log across story variants and instructed revisions. The generic /v1/analyses schema is different, so analyzing a clip first does not eliminate the story preparation vision pass. Assessments can reuse compatible neutral analyses; see composition recipes.

Make a free structured revision

Structured edits run synchronously and return 201 with a new revision. The old revision never changes. Supply the current base_revision_id; concurrent edits from an old base return 409 revision_conflict instead of overwriting someone else's work.

{
  "base_revision_id":"rev_current",
  "operations":[
    {"op":"set_caption","language":"en-US","caption_id":"cap_1","text":"Volunteers restored the garden on Saturday.","fact_ids":["fact_1"]},
    {"op":"trim_clip","variant_id":"en-landscape","clip_id":"clip_1","source_start":2.5,"source_end":8.0}
  ]
}

Send this body to POST /v1/stories/{id}/revisions. Other operations insert, remove and reorder captions or clips, set caption timing and crop coordinates, copy a cut between variants, or set credits and place labels. Inline style and audio changes also produce free revisions. Changes are computed by the server and recorded in the result. See the API reference for exact operation shapes.

Request an instructed revision

An instruction is a separate paid asynchronous operation:

{
  "base_revision_id":"rev_current",
  "variant_id":"en-landscape",
  "instruction":"Make the opening more direct, keep the factual wording and preserve the final reaction shot.",
  "billing":{"max_charge":{"currency":"USD","amount":"0.50"}}
}

Do not combine instruction with structured operations, style or audio changes. The returned job carries story.id, the base revision and variant. A compare-and-set check also runs at completion, so a stale job cannot replace a newer revision.

Audio policy

Choose explicitly:

Audio uploads use the normal upload protocol with an audio/* content type. A video understanding operation still requires footage with a video stream. Choosing a soundtrack does not establish music rights.

Bounds and retention

A story accepts up to eight footage sources, eight variants, 20 minutes of source footage and 512 MiB of source footage plus soundtrack combined. Variants support 16:9, 9:16 and 1:1; the style duration ceiling is 180 seconds. Output is up to 1080p.

renderable_until is the earliest source expiry. Source retention stays seven days; creating a story does not extend it. Both preview rendering and final promotion require unexpired sources. Already created artifacts remain downloadable until their own expiry. Revisions are available for 30 days; render artifacts for seven days. Download deliverables into your own storage if you need them longer.

Continue with preview, approval and delivery.