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.
1. Submit the batch
Give every item a uniquecustom_id (your own catalog ID) so you can match results back:
batch.json:
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 aresult_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
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_centsandbilling_status; onlycompletemeans the charge is final. An optionalmax_cost_centscaps a batch’s spend. - Each item includes
published_formats.validation_status: "not_reported"only means no verdict is exposed on the job; readphysics-qa.jsonin 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.