Batch process media

Run one model on many inputs in a single request, get one callback when the batch finishes.

What you’ll do

Process a folder of product shots through one model in a single call. One callback fires when every item is done.

Prerequisites

• A Runflow API key. Create one.
• The model you want to run. Pick one from /models.
• A list of input URLs or asset IDs.

Steps

1. Create the batch

   POST /v1/models/{model_id}/batches with an array of items, where {model_id} is the slash-delimited provider/model path shown on the model page. Each item is a separate run.

   curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/batches \
     -H "Authorization: Bearer $RUNFLOW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "items": [
         { "input": { "image_url": "https://...01.jpg", "prompt": "white studio" } },
         { "input": { "image_url": "https://...02.jpg", "prompt": "white studio" } },
         { "input": { "image_url": "https://...03.jpg", "prompt": "white studio" } }
       ],
       "callback_url": "https://your-server.com/webhook"
     }'
   

   Response:

   { "id": "01J0...", "status_code": "queued", "items_total": 3 }
   
2. Poll or wait

   Either poll GET /v1/batches/{id} or wait for the callback. Batch records expose status_code; terminal callback payloads expose the same value as status. Batches can also finish as partial_succeeded.

3. Read items

   GET /v1/batches/{id}/items returns one entry per input with the resolved run_id, status_code, and outputs.

Verify it worked

{
  "id": "batch_01J0...",
  "status_code": "succeeded",
  "items_total": 3,
  "items_succeeded": 3,
  "items_failed": 0
}

items_failed: 0? You’re done.

Troubleshooting

Symptom	Likely cause	Fix
Some items fail, others succeed	Per-input validation error	Read each failed item’s failure_message.
Whole batch fails fast	Auth or quota	Check the balance.
Callback never arrives	URL not reachable	See Callbacks: local development.

Related

Runs

Single-input lifecycle.

Callbacks

Async result delivery.