> ## 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 up to 1,000 assets, follow partial results, cancel work and retry selected failures.

Team access must be enabled for your account. Use a **Team API key** from
the Team’s API Access page. Personal keys remain scoped to their individual accounts.
A Team key lets your team use a shared library and the Team's billing
account. Removing or demoting the admin who issued a key disables its access.

Team generation requires `Idempotency-Key`, including single-asset requests
to `POST /v1/assets`. Reuse the same key and body after a timeout. A changed body
returns `409 idempotency_conflict`. Keys are scoped to the Team; replacing an
API key does not create a new submission. Team requests must keep `persist`
enabled. Queued work starts when capacity and available credits permit it;
billing behavior depends on the Team's configured pricing policy. Fixed-price
delivery can charge only on success; legacy metered jobs may report reservations.
Do not infer customer pricing or a card charge from provider usage or budget fields.

## 1. Submit the batch

Submit up to 1,000 asset inputs in one request. Give every item a unique `custom_id`
so your own catalog IDs appear beside its job status:

```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"}
    }
  ]
}
```

For local images, upload through `POST /v1/images` with the **same Team key**
and use the returned `image_id` values in each input. URLs and uploaded images can
be mixed, with up to eight references per asset. Original bytes and view labels
are retained. An image uploaded to a personal account or another Team cannot
be used by this Team key.

Replace example.com URLs with real image URLs, or use uploaded image IDs.

## 2. Track progress

The `202` response contains `batch_id` and a `Location` header. Poll the batch
rather than polling every individual job:

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/v1/batches/{id}` | Progress, processing limit, charges and billing status |
| `GET` | `/v1/batches/{id}/items?limit=100` | Paginated jobs with `custom_id`, index, charges, publication status and result links |
| `POST` | `/v1/batches/{id}/cancel` | Stop queued work and request cancellation of active jobs |
| `POST` | `/v1/batches/{id}/retry` | Create a linked batch for selected failed/cancelled items |

Follow `next_cursor` while `has_more` is true. Successful items remain available
when another item fails. `completed` means all accepted items reached a terminal
state; inspect `succeeded_items` and `failed_items` before treating the batch as
successful. If ingestion is cancelled early, `unsubmitted_items` reports inputs
that never became jobs. Cancellation of running work can remain pending until its
workers are confirmed stopped. Billing status is reported separately from generation status.

## 3. Download successful items

`items_url` links to the authenticated items endpoint. Each item includes
`artifact_status`, `published_formats` and a result link when successful.
Publication records the completed export bundle; it does not guarantee storage
availability at the moment of download. `validation_status: "not_reported"`
means no simulation validation verdict is exposed. It does **not** mean that QA
was skipped: a delivered bundle can contain `physics-qa.json` with executed results
while the public job field remains `not_reported`. Inspect those results and their
input hashes; do not interpret job success as a QA pass. Successful export does not
certify geometry, physics or Isaac compatibility.

See [Billing & limits](/api-limits) for automatic queueing and charge fields, and [Downloads & bundle formats](/api-downloads) for each successful asset.

## Retry selected items

Send `POST /v1/batches/{source_batch_id}/retry` with a new `Idempotency-Key` and:

```json theme={null}
{"item_indices": [0, 7, 12]}
```

Use the original item `index` values from the items endpoint. Select 1–1,000
unique indices of failed or cancelled jobs. Successful, running, unsubmitted,
still-stopping or financially unreconciled items are rejected before acceptance.
The whole selection is checked; the server does not silently skip invalid items.

A `202` returns a **new batch ID**. Its status includes `source_batch_id`; each
new job includes `retry_of_job_id` and retains the original `custom_id`, prompt,
references and view labels. Original jobs/results remain unchanged. The new batch
pins the Team release current at retry acceptance and uses fresh per-job
budgets, subject to the same credit and capacity controls. Retried items queue
automatically within the Team processing limit. Optional `max_cost_cents` applies
to the new batch.

Retry a lost response with the **same key and selection** to recover the same
batch; changing the selection or limits under that key returns `409`. Changing
only selection order is equivalent. A different key authorizes another retry and
may incur another generation charge.

If authoring succeeded and only export failed, use [export-only recovery](/api-jobs#retry-export-without-regeneration) instead of paying to author the asset again.

## Endpoint reference

* [Submit a batch](/api-reference/batches/submit-a-team-asset-batch)
* [Get batch progress](/api-reference/batches/get-batch-progress)
* [List per-item results](/api-reference/batches/list-batch-items-and-per-item-results)
* [Cancel unfinished work](/api-reference/batches/cancel-unfinished-batch-work)
* [Retry selected items](/api-reference/batches/retry-selected-failed-or-cancelled-batch-items)


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