Get a structured ad pack back from one Sume Agent Completion

To get an ad pack back as fields instead of prose, bind a JSON Schema to the run with output_schema and name the deliverable with primary_output_key. Sume then returns output in your shape, with the generated video as a SumeMediaFile whose URL is checked against the media ledger. Keep every property listed in required and express optional values as nullable unions.

A schema for an ad pack

The schema below asks for three text fields and one video. Every property is required, the object closes with additionalProperties: false, and the optional caption uses a nullable union, which is how the strict subset says optional.

{
  "name": "ad-pack/v1",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["hook", "caption", "cta", "video"],
    "properties": {
      "hook": { "type": "string" },
      "caption": { "type": ["string", "null"] },
      "cta": { "type": "string" },
      "video": { "$ref": "SumeMediaFile#" }
    }
  }
}

What the strict subset allows

Read the receipt in the right order

Check output_error before output. On a completed run, output carries your object and filled_by tells you who wrote it: agent means the run submitted the object itself, projection means a fallback pass filled it from what the run produced.

The projection also runs a URL gate. A media URL has to match media the run really generated, and a duration_ms inside a SumeMediaFile must agree with the actual file within 10%. A hallucinated link fails the projection and does not reach you.

Failure modes to plan for

For a pipeline, store the schema with the code that reads it. When the schema changes, version its name, for example ad-pack/v2, so a log line tells you which shape a run was asked for. Never loosen the subset to make a run pass: the rules exist so that the object you get is the object you asked for.

• A schema outside the subset is rejected at submit with details.violations[] naming each broken rule.
• If the run produces a valid object but the key named in primary_output_key is empty, the run is failed with primary_output_missing.
• A degraded run still bills and still has real media on it, but output is null. The webhook marks this outcome: degraded.
• If you want partial results to be legal, drop minItems on arrays and make fields nullable.

Where the spend cap comes in

The Completion still needs generation_spend_cap_usd, and the schema does not change what the run may spend. Pair the schema with a cap that fits one pack, then branch on primary_output_url for the video and on output.hook and output.cta for the copy.