Skip to main content
A batch is a list of asset requests sent in one call. Each item is generated exactly as if you had sent it to POST /v1/assets: same options (references, interactions, variations), same output, same price. Batches save you from managing the queue yourself. With a Personal key, Gizmo starts items as your 20 slots free up, so you can submit 50 at once and the rest start automatically as earlier ones finish. Need more than 50? Submit several batches.
Make sure your balance covers the whole batch before you submit it. Items that start after your credits run out fail with an error; you can retry them after topping up.

1. Submit the batch

Give every item a unique custom_id (your own catalog ID) so you can match results back:
Example batch.json:
For local photos, upload them with the same key first and use the returned image_id values. Replace the example.com URLs with real images. The response is 202 Accepted with a batch_id. Save it. If the response is lost, resend the same body with the same Idempotency-Key to get the same batch back.

2. Track progress

Poll the batch every minute or so rather than polling each job. On the items endpoint, follow next_cursor while has_more is true. The batch status becomes completed when every item has finished, whether it succeeded or not. Check succeeded_items and failed_items, and each item’s status, before treating the batch as a success. One failed item never affects the others. unsubmitted_items counts items still waiting for a slot.

3. Download successful items

Each succeeded item has a result_url pointing at its job. Fetch it and read result.asset.id, then export the asset in the format you need. Exports are one asset and one format per request; there is no single ZIP for a whole batch.

Retry selected items

Use the index values from the items endpoint, and only for items that failed or were cancelled. The request is rejected as a whole if any selected item is not eligible. The response is a new batch ID; its items keep their original custom_id and inputs, and the original batch is unchanged. A retry is a new generation and is charged again, so use a new Idempotency-Key for each retry you intend.

Team batches

Team batches work the same way, with a few differences:
  • Use a Team key from the Team’s API Access page. Images must be uploaded with the same Team key.
  • Items run within the Team’s processing limit, shared with the Team’s single generations. Queued items start automatically.
  • Batch and item responses report settled_spend_cents and billing_status; only complete means the charge is final. An optional max_cost_cents caps a batch’s spend.
  • Each item includes published_formats. validation_status: "not_reported" only means no verdict is exposed on the job; read physics-qa.json in the GLB bundle for executed checks.
  • If an item’s asset was built but its export failed, use export-only recovery instead of generating it again.

Endpoint reference