Preview, approval and delivery

Rendering is explicit. First create a preview of one story revision and variant. A producer reviews its actual MP4 and checks, records approval, then promotes those exact video bytes to a final delivery. A final promotion does not re-encode or start publishing.

Render a preview

POST /v1/renders returns a job:

{
  "revision_id":"rev_current",
  "variant_id":"en-landscape",
  "preview":true,
  "billing":{"max_charge":{"currency":"USD","amount":"0.50"}}
}

The completed job points to GET /v1/renders/{id}. Artifacts include the MP4 video, subtitles when captioned, editable Final Cut Pro 7 XML (xmeml), and a delivery manifest with provenance. XML is a source-referenced edit description; downstream editors may need to relink original media, and font/layout rendering can vary between NLEs.

GET /v1/stories/{id}/renders lists previews and deliveries. The console displays the video, source cuts, captions and automated checks together.

Download artifacts

GET /v1/artifacts/{id} authorizes the caller and returns metadata and a short-lived download_url in cloud mode. Use GET /v1/artifacts/{id}/content with your API key to download directly through an authorized redirect. Signed links last at most 15 minutes and never outlive the artifact's seven-day retention. Treat the link as a temporary bearer credential.

In local development, download_url is null; use the authenticated content route. Test-mode responses are fixtures and are marked as such. Artifact content is available only when a real render produced bytes.

Record human approval

After reviewing the actual preview, call POST /v1/stories/{story_id}/approvals:

{
  "revision_id":"rev_current",
  "variant_id":"en-landscape",
  "preview_render_id":"rnd_preview",
  "actor":"producer-42",
  "acknowledge_checks":["warning_id_from_revision"]
}

The approval binds revision, variant, configuration hash, content hash and exact preview SHA-256. Error checks block approval; enumerate warnings you explicitly reviewed. The actor label is caller-asserted. attested_by records the authenticated API key or console account; it does not independently verify a human identity or establish publication rights.

Changing captions, cuts, style or audio creates a different revision and requires a new preview and approval. List approvals with GET /v1/stories/{id}/approvals; inspect one at GET /v1/story_approvals/{id}.

Promote approved bytes

{
  "revision_id":"rev_current",
  "variant_id":"en-landscape",
  "preview":false,
  "approval_id":"approval_reviewed"
}

Send to POST /v1/renders. The promotion job verifies the approval is still active and matches the exact preview. Its video SHA-256 is identical to the approved preview. It creates a final delivery record and manifest, without charging for another encoding. Preview/final labels live in API metadata; there is no burned-in preview watermark to change the reviewed video.

Both preview rendering and promotion require sources within renderable_until. Promotion cannot extend retention of the shared artifact bytes.

Revoke an approval

POST /v1/story_approvals/{id}/revoke takes {"reason":"Correction requested by editor"}. Revocation prevents subsequent promotion. Previously downloaded or delivered files cannot be recalled; their audit records remain.

All create and revision calls accept Idempotency-Key. Retry the same request with the same key after a network timeout. See idempotency and billing.