Async batches

Generate hundreds of descriptions in a single operation, at a lower price than sync generation.

The batch lifecycle

• Submit the batch with POST /v1/batches — the whole batch's credits are RESERVED at that moment.
• Poll GET /v1/batches/:id — when the provider finishes, that GET ingests the result: it creates the generations, charges successes against the reservation and refunds the rest.
• The batch lands on status "ended" — read the descriptions or export the catalog.

Submitting the batch

The Idempotency-Key header is REQUIRED (without it, 428): a network retry with the same key returns the same batch instead of reserving credits twice.

POST /v1/batches
Idempotency-Key: lote-otono-2026-v1
{ "product_ids": ["…", "…"] }

{ "id": "…", "status": "submitted", … }

Polling ingests

Your GET is what ingests the result as soon as the provider finishes. Poll every 30–60 seconds until you see status "ended" (or "failed" or "cancelled").

GET /v1/batches/{id}

{ "id": "…", "status": "ended", "total": 50, "succeeded_count": 48, "failed_count": 2, … }

Cancelling

POST /v1/batches/:id/cancel cancels an in-progress batch and refunds the full reservation. If the batch already finished (or is being ingested), it responds 409 — do the final poll to close the cycle.