primary_output_key on a headline string: primary_output_url is null

If primary_output_key names a text field such as headline, the receipt echoes that key back and primary_output_url is null, because a string has no URL to resolve. Point the key at the media field instead, for example hero_image.

The resolution order

primary_output_key is up to 64 characters. The receipt resolves primary_output_url in order: the key on your request, then the Format's own key, then the first top-level key that holds a media object or an array that starts with one. For the built-in schema, the fallback order is videos, images, audio, files.

The step stops at a key you named when output has a value under it, even a value that is not media. It moves to the fallback only when the key is missing or empty.

A schema that sets it correctly

Bind the key next to your schema so the receipt shows the one URL your UI needs.

{
  "output_schema": {
    "name": "acme/promo-hero/v1",
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": ["headline", "hero_image"],
      "properties": {
        "headline": { "type": "string" },
        "hero_image": { "$ref": "SumeMediaFile#" }
      }
    }
  },
  "primary_output_key": "hero_image"
}

Why the headline case is quiet

Nothing errors, which is why this one is easy to miss. The run is completed, output is full, and the key you named is echoed back. Only the URL is empty, so a UI that renders primary_output_url shows a blank slot.

Test your key against a real receipt in a pilot, and treat a null primary_output_url on a completed run as a prompt to read primary_output_key and output_error before you suspect the generation.

The same care applies when you set the key yourself. Pick a key that names a generated media file, and read the other fields from the structured output instead of expecting a URL for text.

If you later change the Format's schema, recheck the key as well, since a renamed field would leave the old key pointing at nothing and the URL would be null again.

Tradeoff

The key is a convenience for one primary item. If your Format makes several deliverables, read output and artifacts[] directly instead of forcing one URL to stand for all of them. Both fields are null while the run is not terminal.