Batches

A batch submits a whole shoot in one call: shared defaults at the top, one entry per scene, per-scene overrides where a scene differs. Each scene becomes a regular order; the batch tracks them together.

The model

• Defaults + overrides — options set on the batch apply to every scene; a scene overrides only what it sets. An absent field inherits; an explicit value (even false) wins.
• Atomic intake — the batch is validated as a whole. One invalid scene refuses the entire batch with a 400 before anything runs; nothing partial ever starts.
• One scene, 1-5 brackets — each scene's inputs works exactly like a single order's. Up to 100 scenes per batch.
• Independent outcomes — scenes succeed or fail individually. A failed scene never blocks its siblings; results split into completed and failed.

Submitting a shoot

const batch = await bkbn.batch({
  name: 'shoot-12-rue-vaugirard',
  perspective: true,
  tonecraft: true,
  scenes: [
    { inputs: [living1, living2, living3] },           // HDR brackets, inherits
    { inputs: [facade], sky: 'high_cloud' },             // override
    { inputs: [bedroom], genEdit: 'declutter_local' },
  ],
})

const results = await batch.wait({
  onProgress: (p) => console.log(`${p.completed}/${p.total}`),
  onOrderDone: (o) => console.log('done', o.orderUuid),
})
await results.saveAll('out/')
results.failed                          // a failed scene does NOT throw

Following a batch

GET /v1/batches/:id/events streams the shoot's aggregate progress over SSE — per-order completions plus completed/failed counts — and closes when every scene has settled. GET /v1/batches/:id returns the same aggregate on demand. The SDKs' batch.wait() rides the shared WebSocket instead and returns completed and failed scenes without throwing for individual scene failures. HTTP errors, network errors and timeouts can still throw.

Cancelling a batch

POST /v1/batches/:id/cancel cancels scenes that are still pending or running. Scenes already completed, failed, cancelled or expired keep their state. A scene that completes while cancellation is being applied keeps its result. Repeating the request leaves settled scenes unchanged.

const state = await bkbn.cancelBatch(batchId)
// Or, if you have a BatchHandle: await batch.cancel()

The response contains counters such as data.failed and data.done, plus scene summaries in data.orders. The failed count includes failed, cancelled and expired scenes; inspect each order's status to distinguish them. done means all scenes are terminal, not that they all succeeded. In the SDKs, batch.wait() returns this completed/failed split; cancelled scenes do not make it throw an order-cancellation exception.

Next steps

• Streaming: the SSE and WebSocket contract in detail.
• Features: everything a scene can order.