primary_output_key: how a Format run picks primary_output_url

A Format run resolves primary_output_url in three steps: the primary_output_key on the run request, then the Format's own primary_output_key, then the first top-level key in output that holds a media object. The key is capped at 64 characters, and both fields are null unless the run is completed.

This follows Structured output and Create a run, read on 2026-10-02.

What is the exact resolution order?

Most integrations have one thing to show, so naming it saves you a loop over output. The receipt walks these in order and stops at the first that yields a value.

What if the key is not media?

A key named in step 1 or 2 is echoed back whenever output carries a value under it, including a value that is not media. Point it at a headline string and you get primary_output_key: "headline" with primary_output_url: null, because there is no URL to resolve.

Only a key that is missing from output, or empty there, falls through to step 3. So a wrong key name that happens to exist as text will not silently fall back to your video. Test with a real run and look at both fields.

What does the built-in schema do?

If you bind nothing, output uses the built-in shape and the fallback goes through videos, then images, audio, files. The first non-empty array supplies the URL.

When is the pointer null on purpose?

Both fields are null on any non-terminal status and null when output_error is set. A failed run never gets a pointer, even if it produced partial output, so a check on primary_output_url cannot be fooled by a partial.

If the run satisfied your schema but left the named key empty, the run ends failed with primary_output_missing and output still carries the partial result. That is the intended guard when you loosen a schema to allow nullable fields.

A request that sets it

Name the key on the create call, with the schema that defines it, and read it back from the receipt:

curl -sS -X POST "https://api.sume.com/v1/formats/acme/promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-1042-hero-v1" \
  -d '{
    "instruction": "Make one hero image.",
    "output_schema": {
      "name": "acme/hero/v1",
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hero_image"],
        "properties": { "hero_image": { "$ref": "SumeMediaFile#" } }
      }
    },
    "primary_output_key": "hero_image"
  }'

How should a client read the result?

Send primary_output_key on every run rather than relying on step 3. Step 3 is a convenience for a Format with one obvious file, and it changes if a recipe later adds a second media field above the first.

• Check status is completed before reading anything else.
• Check output_error is null; if it is set, primary_output_url is null and output may be null.
• Read primary_output_url, and if you also need the typed fields, read output using the same key you named.
• Store the URL against your own record. Media URLs are durable media.sume.com HTTPS links that do not expire, but they are public to anyone holding them.

Where can I set the Format-level key?

The Format's own primary_output_key is step 2. It is part of the Format, so every caller inherits it unless a request names another. The request key always wins when output has a value under it.

Because a named key is echoed back whenever output carries a value under it, a typo that matches another text key will produce a null URL without an error. If primary_output_url is null on a completed run, read primary_output_key on the same receipt before suspecting the Format.

How does this interact with partials?

If you loosen a schema so that the deliverable can be null, name that deliverable as the primary key. A run that fills the other fields but leaves the key empty ends failed with primary_output_missing, and output still shows the partial.

That means status, error.code and primary_output_url give you three consistent signals, and you do not have to inspect the shape of output to know whether the cut exists.