Hook line in instruction or input? Sume Format run for ad variants

For ad variants, put the hook line in instruction and keep the product facts in input. A Sume Format run accepts instruction up to 8000 characters, and the docs say instruction wins over the Format's own body, so it is the field that changes the creative per run. The input field is free-form JSON, so it suits the facts that stay the same, such as product name, claim and price. That split keeps ten variants identical except for the one thing you are testing.

What each field does

The call page defines the request body. A run must name at least one of instruction, input, previous_run_id or attachments, and unknown fields give 400 unknown_parameter, so a misspelled key fails fast instead of being ignored.

One body, ten hooks

Keep a constant input object and a list of hooks. Each hook becomes one instruction. In a bulk call each item carries the same body as a single run, so the item is just the instruction plus the shared input. Send an Idempotency-Key with the request, and make it stable per variant, so a retry replays the receipt rather than starting a second run.

curl -sS -X POST https://api.sume.com/v1/formats/sume/sume-video-hook/runs \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Idempotency-Key: hook-03-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Open on the line: Your sunscreen is leaving a white cast.",
    "input": {"product": "Daily SPF 50", "claim": "no white cast"},
    "generation_spend_cap_usd": 5
  }'

Replays and conflicts

A replay of the same key with the same body gives 200 with idempotency_hit true and the original receipt. The same key with a different body gives 409 idempotency_conflict, and nothing runs. A concurrent duplicate gives 409 idempotency_key_in_use, which is retryable. The consequence for variants is simple: when you edit a hook, change the key, for example by adding a version suffix. Reusing the old key with a new hook is the most common way to get a conflict.

The receipt carries the key under trigger.idempotency_key, so you can match runs to your hook list without storing run ids on your side first.

When input is the better home

If the hook is a structured value the Format reads, such as a headline slot, use input and test it on one run first. We did not verify which catalog Formats read which input keys, since the docs describe input as free JSON. Read the Format's io profile and description, and use instruction when you are unsure, because instruction is the documented override.

Checklist

• Hook goes in instruction.
• Stable facts go in input.
• One idempotency key per hook version.
• A generation_spend_cap_usd on every run.
• Poll with a key that has formats:read.

A variant sheet that stays honest

Keep a sheet with one row per hook: the hook text, the idempotency key, the item index and the run id once you have it. The index in a bulk queue is the position of the item, so a sheet that preserves order can be joined back with no guessing. When a hook wins, you want to rerun it at higher quality or in another aspect ratio, and the sheet tells you exactly which instruction to send.

Avoid packing two ideas into one hook. A hook that changes the opening line and the ending together tells you that something worked, not what. Test one change per row, and add endings as a second pass on the winning hooks only. That keeps the number of runs low, and each run has a spend cap, so the worst-case cost of the whole sheet is the number of rows times the cap.

Expect 400 unknown_parameter for a misspelled field, 400 when the body names none of instruction, input, previous_run_id or attachments, and 403 when the key lacks formats:write. All three happen before a run exists, so they cost nothing. Fix the body and resend with the same key if the first attempt created nothing.