> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizmo.antimlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a batch

> Submit many assets in one request, collect results as they finish, and retry only what failed.

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.

| | Personal key | Team key |
| - | - | - |
| Items per batch | Up to 50 | Larger catalogs in one request |
| Running at once | Your 20 in-progress slots, shared with single generations | The Team's processing limit |
| Price | Each item priced like a single generation | The Team's configured pricing |

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.

> [!WARNING]
>
> 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](#retry-selected-items) after topping up.

## 1. Submit the batch

Give every item a unique `custom_id` (your own catalog ID) so you can match results back:

```bash theme={null}
curl --fail-with-body "https://api.gizmo.antimlabs.com/v1/batches" \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-catalog-001" \
  --data-binary @batch.json
```

Example `batch.json`:

```json theme={null}
{
  "items": [
    {
      "custom_id": "mug-001",
      "input": {
        "prompt": "Recreate this ceramic mug",
        "reference_images": [
          {"url": "https://example.com/mug-front.jpg", "view": "front"},
          {"url": "https://example.com/mug-back.jpg", "view": "back"}
        ]
      }
    },
    {
      "custom_id": "bowl-002",
      "input": {"prompt": "A white ceramic bowl, 16 cm in diameter"}
    },
    {
      "custom_id": "plate-003",
      "input": {
        "prompt": "A round dinner plate, 27 cm",
        "appearance_variants": true,
        "variant_count": 3
      }
    }
  ]
}
```

For local photos, [upload them](https://docs.gizmo.antimlabs.com/api-references.md) 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

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/v1/batches/{id}` | Overall status and counts |
| `GET` | `/v1/batches/{id}/items?limit=100` | One entry per item with its `custom_id`, `index`, `status` and `error` |
| `POST` | `/v1/batches/{id}/cancel` | Stop items that have not finished |
| `POST` | `/v1/batches/{id}/retry` | Retry selected failed or cancelled items as a new batch |

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](https://docs.gizmo.antimlabs.com/api-downloads.md) 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

```bash theme={null}
curl --fail-with-body -X POST "https://api.gizmo.antimlabs.com/v1/batches/BATCH_ID/retry" \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-catalog-001-retry-1" \
  -d '{"item_indices": [0, 7, 12]}'
```

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](https://docs.gizmo.antimlabs.com/api-jobs.md#retry-export-without-regeneration) instead of generating it again.

## Endpoint reference

* [Submit a batch](https://docs.gizmo.antimlabs.com/api-reference/batches/submit-an-asset-batch.md)
* [Get batch progress](https://docs.gizmo.antimlabs.com/api-reference/batches/get-batch-progress.md)
* [List per-item results](https://docs.gizmo.antimlabs.com/api-reference/batches/list-batch-items-and-per-item-results.md)
* [Cancel unfinished work](https://docs.gizmo.antimlabs.com/api-reference/batches/cancel-unfinished-batch-work.md)
* [Retry selected items](https://docs.gizmo.antimlabs.com/api-reference/batches/retry-selected-failed-or-cancelled-batch-items.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.