Límites de solicitudes

Dos límites mantienen predecible la latencia para todos: un límite de solicitudes para las llamadas autenticadas y otro de concurrencia para las generaciones que se ejecutan a la vez. Si superas el de solicitudes, la llamada recibe 429 rate_limited y no se cobra nada. Si superas el de concurrencia, no se rechaza nada: la generación espera en la cola de tu cuenta y empieza en cuanto termina una de las tuyas.

Límites predeterminados#

El límite de solicitudes funciona como un depósito de tokens: puedes enviar hasta 20 solicitudes de una vez y la capacidad se repone a razón de 10 por segundo. El tráfico constante por debajo de 10 solicitudes por segundo nunca se limita.

La cola#

• Una generación que supera tu límite de concurrencia se acepta como siempre: recibes su id al instante, su precio queda reservado y su estado es queued. Empieza sola en cuanto termina una de tus generaciones, la más antigua primero.
• La espera no cuenta para el tiempo límite de una generación: una generación en cola nunca falla ni caduca por esperar.
• Una generación que sigue esperando en tu cola se puede cancelar (POST /generations/{id}/cancel) o eliminar en cualquier momento, y lo reservado se reembolsa al instante. Una vez que empieza, se aplican las reglas habituales de cancelación.
• Tu cola admite hasta 10 × tu límite de concurrencia (200 en una cuenta nueva). A partir de ahí, la solicitud recibe 429 rate_limited y no se crea ni se cobra nada.
• Cada cuenta tiene su propia cola y las generaciones en espera no ocupan capacidad: una cola larga nunca retrasa las generaciones de otras cuentas.

Consulta tus límites#

La tabla muestra los valores predeterminados. Los límites de tu cuenta, y cuántas de sus generaciones están en curso, aparecen en Panel → Ajustes y en el campo limits de GET /api/v1/account (y de la herramienta MCP get_account):

{
  "object": "account",
  "balance_usd": 42.5,
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

concurrent_generations es cuántas generaciones pueden ejecutarse a la vez (las demás esperan en tu cola) y in_flight cuántas hay en curso ahora, incluidas las que están en cola; requests_per_second y burst son la tasa de solicitudes y la ráfaga, para la cuenta y para cada una de sus claves de API.

Al alcanzar un límite#

{
  "error": {
    "code": "rate_limited",
    "message": "Your queue is full: 200 generations are already waiting for your 20 concurrent slots (up to 200 can wait). Nothing was submitted or charged. Retry when some have finished (webhook_url tells you when), or cancel queued ones; GET /api/v1/account shows your limits. For a higher limit, contact us: contact@cheapergen.com."
  }
}

Cada 429 incluye una cabecera Retry-After (segundos de espera). Si se alcanzó un límite, el mensaje lo indica; si tu cola está llena, también dice cuántas generaciones están esperando.

• Límite de solicitudes:: espera un momento y vuelve a intentarlo con retroceso exponencial y fluctuación aleatoria (empieza con aproximadamente un segundo). Consulta Reintentar de forma segura.
• Cola llena: el 429 por concurrencia solo llega cuando tu cola está llena. Espera a que terminen algunas generaciones (un webhook_url te avisa) o cancela las que están en cola, y luego envía más.

Mantente dentro de los límites#

Usa webhooks en vez de consultar el estado continuamente#

Consultar decenas de tareas cada segundo agota el límite de solicitudes. Proporciona un webhook_url para que te avisemos; consulta Webhooks. Si consultas el estado, aumenta el intervalo a 5–10 segundos para los videos.

Pon las solicitudes en cola de tu lado#

Las ráfagas cortas no son problema: tu cola las absorbe. Para lotes más grandes que tu cola, guarda el trabajo pendiente de tu lado y envía a medida que terminan las generaciones (los webhooks te avisan), así nunca recibirás el 429 de cola llena.

Usa una clave por servicio#

El límite de solicitudes se cuenta por clave, pero la concurrencia se cuenta por cuenta. Repartir el tráfico entre más claves no aumenta la cantidad de generaciones que puedes ejecutar a la vez.