Generate descriptions

Synchronous generation: one call, one description per language. This operation charges credits.

Synchronous generation

With the generate scope, request a product's description. The call waits for the engine to finish and returns the full result:

POST /v1/generations
Idempotency-Key: gen-camisa-001-v1
{ "product_id": "…", "languages": ["es", "en"] }

languages is optional: without it, your organization's configured language set is used. You're charged ONLY for the languages that succeed — a failing language doesn't charge or abort the others. The response includes what was charged and your balance:

{
  "results": [ { "language": "es", "status": "succeeded", … } ],
  "total_credits_charged": 20,
  "balance": 1214
}

Send a unique Idempotency-Key per operation (recommended): if the request drops mid-flight, retrying with the same key returns the original result instead of generating — and charging — again. See the Idempotency guide.

What it can respond

Code	Meaning
`402`	Insufficient balance. Cut off before generating: no partial charge.
`404`	The product doesn't exist (or belongs to another organization — indistinguishable).
`429`	Rate limit (retry after Retry-After) or daily AI spend cap (no Retry-After).
`503`	Service paused (maintenance / AI off). Nothing was charged.

Lots of products?

For volume use async batches: cheaper per description and no open connections to hold. Sync generation shines for one-at-a-time flows (e.g. generating when a product is created).