Black Friday ad copy and video in one call: an output_schema example

One Format run can return the ad copy and the video in a single typed result. Bind an output_schema with a headline, a caption and a video that uses { "$ref": "SumeMediaFile#" }, and name the video in primary_output_key.

The request

The schema follows Sume's strict rules: the root is an object, additionalProperties is false, and every property is listed in required. A field you might not have is a nullable union, not an omitted key.

{
  "instruction": "Black Friday teaser, 9:16, 8 seconds.",
  "input": { "product": "Merino beanie", "offer": "30% off, today only" },
  "output_schema": {
    "name": "shop/bf-teaser/v1",
    "strict": true,
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["headline", "caption", "video"],
      "properties": {
        "headline": { "type": "string", "maxLength": 60 },
        "caption": { "type": "string" },
        "video": { "$ref": "SumeMediaFile#" }
      }
    }
  },
  "primary_output_key": "video"
}

What you get back

• output holds the typed object; primary_output_url resolves from primary_output_key.
• A video URL is accepted only if the run generated it. You cannot make the agent fill the field with an arbitrary link.
• duration_ms on a media value is checked against the file within 10 percent.

When it does not fit

If the agent cannot satisfy the schema the run fails with an output_error such as output_schema_unsatisfied or primary_output_missing; it does not hand you a half-filled object. Handle those in your failure branch, and note the schema keywords are an allowlist: oneOf, allOf and nullable are rejected, so use anyOf or a type array.