Personalized video at scale: one recipe, one run per person

To make personalized video at scale, keep one video recipe fixed and change only each person's data (a first name, a company, an offer), generate one video per person from your list, and send each person a link to their own video. Most of the work is bookkeeping: what varies per person, how each finished video maps back to the right row, and who else can open the link.

The Sume details below come from the Bulk runs, Create a run and Runs and results docs, read on 2026-09-27.

What changes per person, and what stays fixed?

The recipe stays fixed: the look, the length, the structure, what every video must say. In Sume that is a Format, a saved recipe you call by handle and slug. Each person's details travel in the run's input, a JSON object you shape yourself. Sume writes input whole to a file in the run's workspace and tells the agent it is caller-supplied data, not instructions; the docs name a customer's message as exactly the kind of text that belongs there rather than in instruction.

Try the recipe on a few real rows before the whole list. Runs over the API are unattended, so nobody reviews each video before it is made. One bulk request then covers up to 100 people:

curl -sS -X POST "https://api.sume.com/v1/formats/acme/welcome-video/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-batch-001" \
  -d '{
    "concurrency": 4,
    "items": [
      {
        "input": { "first_name": "Dana", "company": "Example Co" },
        "idempotency_key": "lead-4812-welcome-v1",
        "generation_spend_cap_usd": 10,
        "communication": { "webhook_url": "https://example.com/hooks/sume" }
      },
      {
        "input": { "first_name": "Luis", "company": "Sample Labs" },
        "idempotency_key": "lead-4813-welcome-v1",
        "generation_spend_cap_usd": 10,
        "communication": { "webhook_url": "https://example.com/hooks/sume" }
      }
    ]
  }'

How many people can one request cover?

Up to 100. One bulk request carries 1–100 items, each the same body as a single run, with 1–16 of them in flight at once, so a list of 1,000 people is ten requests. Queue completed only means every item is terminal, not that every video succeeded, so check counts.failed before you send anything; Format bulk runs covers how the queue drains.

How do I match each video to the right person?

Not from the output. input does not reach the structured output, so a name or an id you sent comes back only if the run happens to repeat it. The docs say to keep your identifiers on your side, keyed by the run id or by your Idempotency-Key:

• Store the queue's items[] against your rows. Items keep your submission order, each with its index and, once dispatched, its child run_id.
• Give each item its own idempotency_key built from your row id, as in the example. In current code that key becomes the child run's own key, which the run receipt reports as trigger.idempotency_key, and a run webhook's payload is that receipt.
• Dedupe deliveries on the envelope's request_id, which equals the run id and repeats on every retry.

Can each person's video stay private?

Only as private as its link. Run media URLs are durable media.sume.com HTTPS URLs that don't expire, and they are public to anyone holding the URL; the docs say to proxy or copy them if your product needs per-customer access control. When a plain link is not enough, copy the file to your own storage and send a link you control.

Can a talking presenter say each person's name?

Yes, by writing the name into the script. POST /v1/avatar-1.0/talking-video turns a ready avatar (avatar_handle) and a script into a talking video, and accepts scripts Sume estimates at 4–60 seconds. Send one request per person, each with its own Idempotency-Key. In current code the avatar speaks English only. Listen to a sample of names before you send the whole list; talking avatar video from a script covers the call.