Tutorial

Límites de velocidad de la API de generación de imágenes explicados: qué esperar y cómo HiAPI gestiona los picos de tráfico

Jun 28, 2026

Lo que realmente significa "límite de velocidad" en las API de imágenes

Cuando una solicitud de generación de imágenes falla con HTTP 429, o cuando tu trabajo por lotes se atasca exactamente en el mismo número de concurrencia una y otra vez, te estás topando con un límite de velocidad, no con un bug. Todas las API de imágenes de nivel de producción limitan el tráfico en al menos una de tres dimensiones, y entender estas diferencias es fundamental para depurar:

RPM (solicitudes por minuto): el número de llamadas POST que puedes emitir en una ventana móvil de 60 segundos. Amigable con los picos y de recuperación rápida.
RPD (solicitudes por día): un tope diario, normalmente ligado al nivel de tu plan. Se restablece a medianoche UTC (o en el día de facturación de tu cuenta).
Concurrencia / tareas en curso: el número de tareas de imagen que pueden ejecutarse simultáneamente. Aunque el RPM sea normal, la quinta tarea en curso se pondrá en cola o se rechazará.

En la generación de imágenes en concreto, el cuello de botella casi siempre es la concurrencia, no el RPM: una sola tarea de 1024×1024 puede tardar de 8 a 30 segundos de extremo a extremo, así que 10 tareas en paralelo ≠ 10 RPM. Confundir ambas cosas es la causa más común de "mis reintentos están empeorando la situación".

Causas comunes ordenadas por frecuencia

Tu paralelismo supera el límite de concurrencia. La causa más probable. Tu bucle emite 50 llamadas POST /v1/tasks de golpe, el proveedor acepta las primeras N y el resto devuelve 429. Los límites de concurrencia de la mayoría de los proveedores no se documentan por clave: se infieren según tu nivel.
Tormenta de reintentos tras un error transitorio. Una tarea devuelve 5xx y dispara inmediatamente un reintento; todas las demás tareas en curso hacen lo mismo, y tu concurrencia efectiva se duplica en un segundo.
Límite de RPM por modelo que desconoces. Una clave general de nivel alto puede seguir limitada por la dimensión del modelo, sobre todo en modelos nuevos o avanzados. Llamar a gpt-image-2 y flux-1-pro con la misma clave no significa que compartan una cuota.
Cuota diaria agotada a mediodía. Menos común pero muy desconcertante: tus solicitudes funcionan y, de repente, un día empiezan a fallar siempre a la misma hora del reloj. Siempre es el RPD.
Vecinos ruidosos en una subcuenta compartida. Si configuras claves por entorno pero comparten una cuenta de facturación, el tráfico de preproducción se come la cuota de producción.

Pasos para solucionarlo

Ejecuta los siguientes pasos en orden. Cada uno aísla una dimensión distinta.

Lee el cuerpo de la respuesta de error, no solo el código de estado. Un 429 real de HiAPI tiene este aspecto:
```
{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "hiapi_error",
    "request_id": "req_01HXXXXXXXXXXXXXXX"
  }
}
```
Anota el request_id. Es el único dato que permite al equipo de soporte rastrear exactamente qué límite activaste.
Distingue un 429 de un 401. Un 401 con {"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} no es un límite de velocidad, sino un fallo de autenticación o de permisos. No añadas retroceso ante un 401; no se convertirá en 200 por mucho que esperes.

Limita primero la concurrencia del cliente y después el número de reintentos. Un semáforo sencillo basta:

import asyncio, httpx
sem = asyncio.Semaphore(4)  # Ajusta este valor al límite de concurrencia del proveedor

async def submit(client, payload):
    async with sem:
        return await client.post("https://api.hiapi.ai/v1/tasks", json=payload)

Empieza por 4. Aumenta el valor solo cuando el lote completo se ejecute sin un solo 429.

Usa retroceso exponencial con jitter completo solo ante un 429.

import asyncio, random
async def backoff(attempt):
    # 1s, 2s, 4s, 8s, con un máximo de 30s, aleatorizado para evitar el efecto estampida
    delay = min(30, 2 ** attempt) * random.random()
    await asyncio.sleep(delay)

Fija el número máximo de reintentos en 5. Después, expón el fallo: no reintentes indefinidamente.

Respeta Retry-After cuando esté presente. Si la respuesta incluye una cabecera Retry-After, el proveedor te indica explícitamente cuándo se restablece la ventana. Ese reintento debe usar ese valor en lugar del retroceso que hayas calculado.
Separa las claves por entorno. Si preproducción y producción comparten una clave, también comparten el límite de concurrencia. Una clave por entorno más una clave por grupo de trabajo de alto tráfico es la forma más barata de resolver esa sensación de "el límite es más bajo de lo que dice la documentación".

Cómo gestiona HiAPI los picos de tráfico

HiAPI expone un endpoint POST /v1/tasks que acepta tu tarea y devuelve inmediatamente el id de la tarea; después consultas el estado de finalización. Esta separación es importante para el cálculo de límites de velocidad: la llamada de creación es barata y rápida, así que el límite de RPM es holgado; el trabajo pesado lo controla la concurrencia en el lado del modelo, que es donde debe estar. Cuando el proveedor posterior está congestionado, la llamada de creación sigue teniendo éxito: tu tarea simplemente espera en la cola y GET /v1/tasks/{id} devuelve status: "queued" hasta que se abre un hueco. Nunca verás un 429 por la presión transitoria posterior; solo lo verás cuando tú superes la cuota de tu propia clave.

Esta es la razón práctica por la que los equipos migran de una integración directa con el proveedor a HiAPI cuando su carga de trabajo de imágenes supera la capacidad de una sola cuenta: una clave Bearer, un presupuesto de límite de velocidad razonable y picos absorbidos por la cola en lugar de por tu bucle de reintentos.

Ejemplo mínimo de verificación

Úsalo para confirmar que tu clave funciona y que la configuración de concurrencia es razonable. Envía una tarea de imagen a gpt-image-2 e imprime el id de la tarea:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "una sola manzana roja sobre una mesa de madera, luz natural suave",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Respuesta esperada:

200 con {"id":"task_...","status":"queued"} → la clave funciona y la cuota está bien.
429 con {"error":{"code":"rate_limit_exceeded",...}} → has superado el límite de RPM, RPD o concurrencia. Reduce la velocidad siguiendo los pasos de solución anteriores.
401 con {"error":{"code":"permission_denied",...}} → fallo de autenticación, no un límite de velocidad. Revisa tu clave.

Repite esta llamada con un bucle rápido de seq 1 10 | xargs -n1 -P10 curl ... para encontrar tu límite de concurrencia: el primer código devuelto que sea 429 marca tu límite efectivo.

Lecturas relacionadas

Diagnóstico de tareas colgadas y tiempos de espera de HiAPI: para cuando una tarea permanece en estado queued o processing más de lo esperado.
Por qué no se dispara la devolución de llamada de tu tarea de HiAPI: resolución de problemas de devoluciones de llamada asíncronas del flujo de /v1/tasks.
Resolver el error model_not_available: una categoría de error adyacente que a menudo se malinterpreta como límite de velocidad.
Catálogo de modelos: precios por modelo y tipos de endpoint.
Precios: desglose por nivel.

Preguntas frecuentes

¿HiAPI publica valores de RPM para gpt-image-2? Los límites dependen del nivel y pueden cambiar a medida que los proveedores ajustan sus propios topes. Consulta tu panel para ver los límites efectivos actuales en lugar de fijar en el código los números de un artículo de blog.

¿Por qué los reintentos a veces empeoran el 429? Reintentar con un sleep(1) ingenuo en N workers en paralelo convierte un 429 en N reintentos sincronizados que vuelven a chocar todos a la vez. Usa jitter completo (sleep * random.random()) en lugar de un retardo fijo.

¿HiAPI cobra por las respuestas 429? No. Las creaciones de tareas fallidas (429, 401, 4xx en general) no se facturan. Solo pagas por las tareas que producen una salida con éxito.

¿Aumentar la concurrencia del cliente eleva mi límite? No. El límite de concurrencia lo fija el servidor por clave. El paralelismo del cliente solo determina si te mantienes por debajo del límite o lo activas.

¿Cuál es la diferencia entre RPM y TPM? Las API de imágenes limitan por solicitud (RPM), no por token (TPM): las tareas de imagen no tienen una unidad de "token" significativa. Si ves un límite de TPM en el panel, se aplica a los endpoints de texto/chat, no a las tareas de imagen de /v1/tasks.

¿Debo usar una clave de alta concurrencia o varias claves de baja concurrencia? Para cargas de trabajo de imágenes, una clave por grupo de trabajo lógico es el modelo mental más sencillo. Varias claves bajo una misma cuenta de facturación no multiplican realmente tu cuota: la comparten.

¿Puedo solicitar un límite de concurrencia mayor? Sí, una vez que demuestres un uso sostenido en tu nivel actual. Proporciona al equipo de soporte el request_id de un 429 representativo y podrán rastrear qué dimensión estás alcanzando.

¿Por qué no veo la cabecera Retry-After? No todos los proveedores la envían. Si falta, recurre al retroceso exponencial con jitter que empieza en 1 s. Si está presente, ese reintento debe confiar en ella.