reference_ingest_semantic_unavailable: what to do instead

reference_ingest_semantic_unavailable means you sent semantic: true to POST /v1/reference-ingest, and Sume refuses it until the enrichment pass ships. reference_ingest_unavailable is a different error: the media runtime has no reference-ingest Function yet, and the docs say to use video_inspect.

Neither is a bug in your request body. Both are stable codes meant to be branched on.

What does reference ingest give you without semantics?

Facts, not interpretation: frame-exact shots from ffmpeg scdet and PySceneDetect voting together, a sharpest keyframe per shot with palette, luma and a motion class, OCR text tracks, audio facts and a labeled strip. The purpose field (reference_remix, brief_format, face_swap, qa) is stored and not interpreted.

So there is no hook label, no "this is a problem-solution ad" field. Anything like that is a judgement you or your agent makes from the manifest.

Which errors map to which fix?

Branch on the code rather than the message.

What about the old video analyses route?

Video analyses (typed scenes[]) is legacy. On dest it answers 410 video_analysis_retired; production keeps accepting creates until #5953 PR-C2, at a fixed $0.30 per analysis. The docs say not to start new work on it. Semantic questions on dest are video_analyze and video_segment only when those names appear in tools_list.

Do not assume a 410 on dest is a production outage.

How should an agent be written around these refusals?

Code the manifest path as the default and the fallbacks as explicit branches. On reference_ingest_unavailable, call video_inspect for the probe and stills, and read the stills yourself. On reference_ingest_semantic_unavailable, resend without semantic. Neither case should retry the same body, because both are deterministic refusals, not transient errors.

Remember the jobs model too. Reference ingest defaults to mode: sync: it waits up to 30 seconds and answers 200 with the manifest, otherwise 202 with a queued job you poll with jobs_wait then jobs_result (result kind reference_video_manifest). A 202 is not a failure.

How do I tell which surfaces are live for me?

Call tools_list on the hosted MCP or read the OpenAPI. Where a flag gates a route, the docs say so: these surfaces are listed where the matching environment flag allows them (development auto-on, production opt-in), so check tools_list or the OpenAPI before you build on one.

What does reference ingest cost?

The manifest is unbilled: it is CPU work on the media runtime, like video_frames. Only speech.allow_billed_stt can add a charge. It reserves the video inspect transcript rate ($0.01 per audio minute) per rounded-up minute of duration_seconds (one minute if absent) and settles to what ran, so a silent clip or one with no speech settles to zero and the manifest carries a stt_skipped_* warning.

For budgeting, assume zero for the manifest and at most $0.05 for a transcript on a clip of up to 300 seconds.