Video understanding

Use an analysis when your application needs to understand what happens over time. An analysis returns observations, events, keep moments and cut candidates with source timecodes. It can include audio. Use screening for a cheaper category check, segmentation for a labelled timeline, and assessment for judgments against your own editorial criteria.

Analyze a clip

curl https://api.story0.com/v1/analyses \
  -H "Authorization: Bearer $STORY0_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: analysis-storm-001" \
  -d '{
    "input": {"url": "https://dev.story0.com/footage/storm-rushes-720.mp4"},
    "instruction": "Describe the sequence of visible actions and flag useful moments for an editor.",
    "playback_policy": "sound_optional",
    "billing": {"max_charge": {"currency": "USD", "amount": "0.50"}},
    "metadata": {"external_id": "storm-001"}
  }'

The response is a job. Wait for job.succeeded, then fetch job.result.url, or retrieve GET /v1/analyses/{result_id}. A ready input.asset_id can replace input.url, so several operations can reuse one upload.

input requires exactly one of asset_id and url. Analysis requests are strict: unsupported fields are rejected.

Read the evidence

A result includes:

• summary: a concise account of the submitted footage.
• observations: timed evidence with an importance of keep, cut or neutral.
• events: specific events with time ranges.
• keep_moments and cut_candidates: suggestions an editor can inspect.
• hook and payoff: optional evidence records, or null when not established.
• coverage: modalities, sampling limits and completed or failed chunks.
• review: whether review is needed and the reasons.

Evidence has id, kind, start, end and description. kind distinguishes seen, heard and inferred. An inferred event is an interpretation; do not present it as directly observed fact. All intervals are [start, end) in seconds from the source asset.

Sound and coverage

sound_off omits the audio track. sound_optional includes audio when available. sound_required asks for audio and marks missing audio as a review issue; it does not manufacture sound evidence. Inspect coverage.modalities for the modalities actually submitted.

Long footage is processed in chunks of at most 120 seconds. The result lists their source ranges and status. If a recoverable model failure affects one chunk, a successful job can return a partial analysis with coverage.complete: false; route it to review. If every chunk fails, the job fails. A job being successful means the operation produced its typed result, not that every source second was understood.

coverage.sampling_fps describes the proxy. coverage.provider_sampling: "provider_default" means the inference engine applies its own sampling. Fast action, small text and brief transitions can be missed. Timecodes are evidence locations, not frame-accurate editing guarantees.

Reuse and review

Compatible observations can be reused within your account when source content and analysis configuration match. Reuse never crosses accounts. Receipts identify the charge; do not infer a discount solely from making two requests close together.

Results are immutable. Keep your review decision alongside the result ID, and use feedback to record corrections. An analysis neither clears media rights nor approves publication.