Generar descripciones

La generación síncrona: una llamada, una descripción por idioma. Esta operación cobra créditos.

Generación síncrona

Con el scope generate, pide la descripción de un producto. La llamada espera a que el motor termine y devuelve el resultado completo:

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

languages es opcional: sin él se usa el set de idiomas configurado de tu organización. Se cobra SOLO por los idiomas que salen bien — un idioma que falla no cobra ni aborta los demás. La respuesta incluye lo cobrado y tu saldo:

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

Manda un Idempotency-Key único por operación (recomendado): si el request se corta por red, el reintento con la misma key devuelve el resultado original en vez de generar — y cobrar — de nuevo. Ver la guía de Idempotencia.

Qué puede responder

Código	Significado
`402`	Saldo insuficiente. Se corta antes de generar: no hay cobro parcial.
`404`	El producto no existe (o no es de tu organización — no se distingue).
`429`	Límite de tasa (reintenta tras Retry-After) o tope de gasto diario de IA (sin Retry-After).
`503`	Servicio en pausa (mantenimiento / IA apagada). No se cobró.

¿Muchos productos?

Para volumen usa los lotes asíncronos: más baratos por descripción y sin mantener conexiones abiertas. La generación síncrona brilla para flujos uno-a-uno (por ejemplo, generar al dar de alta un producto).