Tutorial

Limites de taxa da API de geração de imagens explicados: o que esperar e como a HiAPI lida com picos de tráfego

Jun 28, 2026

O que "limite de taxa" realmente significa em APIs de imagem

Quando uma solicitação de geração de imagens falha com HTTP 429, ou quando seu trabalho em lote trava sempre no mesmo número de concorrência, você está diante de um limite de taxa — não de um bug. Toda API de imagem de nível de produção limita o tráfego em pelo menos uma de três dimensões, e entender essas diferenças é essencial para depurar:

RPM (solicitações por minuto) — o número de chamadas POST que você pode fazer em uma janela móvel de 60 segundos. Amigável a picos, recupera-se rapidamente.
RPD (solicitações por dia) — o teto diário, geralmente vinculado ao nível do seu plano. Reinicia à meia-noite UTC (ou no dia de cobrança da sua conta).
Concorrência / tarefas em andamento — o número de tarefas de imagem que podem ser executadas ao mesmo tempo. Mesmo com o RPM normal, a quinta tarefa em andamento será enfileirada ou rejeitada.

No caso específico da geração de imagens, o gargalo é quase sempre a concorrência, não o RPM — uma única tarefa de 1024×1024 pode levar de 8 a 30 segundos de ponta a ponta, então 10 tarefas paralelas ≠ 10 RPM. Confundir os dois é a causa mais comum do "minhas novas tentativas pioraram a situação".

Causas comuns ordenadas por frequência

Seu paralelismo excedeu o limite de concorrência. A causa mais provável. Seu loop dispara 50 chamadas POST /v1/tasks de uma vez, o provedor aceita as primeiras N e o restante retorna 429. O limite de concorrência da maioria dos provedores não é documentado por chave — ele é inferido do seu nível.
Tempestade de novas tentativas após erros transitórios. Uma tarefa retorna 5xx e dispara uma nova tentativa imediata, todas as outras tarefas em andamento fazem o mesmo, e sua concorrência efetiva dobra em um segundo.
Limite de RPM por modelo que você desconhece. Uma chave genérica de nível alto ainda pode estar sujeita a limites na dimensão de modelo, especialmente para modelos novos ou avançados. Chamar gpt-image-2 e flux-1-pro com a mesma chave não significa que compartilhem a mesma cota.
Cota diária esgotada ao meio-dia. Menos comum, porém mais confuso — suas solicitações funcionam normalmente e depois começam a falhar todos os dias no mesmo horário. É sempre o RPD.
Vizinhos barulhentos em subcontas compartilhadas. Se você configura chaves por ambiente, mas elas compartilham uma conta de cobrança, o tráfego de homologação consome a cota de produção.

Passos de correção

Execute os passos abaixo em ordem. Cada passo isola uma dimensão diferente.

Leia o corpo da resposta de erro, não apenas o código de status. Um 429 real da HiAPI tem a seguinte aparência:
```
{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "hiapi_error",
    "request_id": "req_01HXXXXXXXXXXXXXXX"
  }
}
```
Anote o request_id. É a única informação que permite à equipe de suporte rastrear exatamente qual limite você acionou.
Distinga 429 de 401. Um 401 com {"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} não é um limite de taxa — é uma falha de autenticação ou permissão. Não adicione backoff a um 401; ele nunca se tornará 200, por mais que você espere.

Limite a concorrência do cliente antes de limitar as novas tentativas. Um semáforo simples já resolve:

import asyncio, httpx
sem = asyncio.Semaphore(4)  # ajuste este valor ao limite de concorrência do provedor

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

Comece com 4. Só aumente depois que um lote inteiro de tarefas rodar sem nenhum 429.

Use backoff exponencial com jitter completo apenas em 429.

import asyncio, random
async def backoff(attempt):
    # 1s, 2s, 4s, 8s, teto de 30s, randomizado para evitar efeito de manada
    delay = min(30, 2 ** attempt) * random.random()
    await asyncio.sleep(delay)

Limite as novas tentativas a 5. Depois disso, exponha a falha — não repita indefinidamente.

Quando existir Retry-After, siga-o. Se a resposta trouxer um cabeçalho Retry-After, o provedor está dizendo explicitamente quando a janela reinicia. Essa nova tentativa deve usá-lo em vez do backoff calculado por você.
Separe chaves por ambiente. Se homologação e produção compartilham uma chave, seu limite de concorrência também é compartilhado. Uma chave por ambiente + uma por pool de trabalho de alto tráfego é a forma mais barata de resolver "o limite parece menor do que a documentação diz".

Como a HiAPI lida com picos de tráfego

A HiAPI expõe um endpoint POST /v1/tasks que aceita sua tarefa, retorna imediatamente o id da tarefa, e depois você consulta o status de conclusão. Essa separação é importante para o cálculo de limites de taxa: a chamada de criação é barata e rápida, então o limite de RPM é folgado; o trabalho pesado é controlado pela concorrência no lado do modelo, que é onde ele deve estar. Quando o provedor downstream está congestionado, a chamada de criação continua tendo sucesso — sua tarefa apenas aguarda na fila, e GET /v1/tasks/{id} retorna status: "queued" até que uma vaga abra. Você nunca vê um 429 por pressão transitória do downstream; só vê quando você excede a cota da sua própria chave.

Essa é a razão prática para migrar de uma integração direta com o provedor para a HiAPI quando a carga de trabalho de imagens da equipe excede a capacidade de uma única conta: uma chave Bearer, um orçamento de limite de taxa raciocinável, e picos absorvidos pela fila em vez de pelo seu loop de novas tentativas.

Exemplo mínimo de verificação

Use-o para confirmar que sua chave está funcionando e que a configuração de concorrência é razoável. Ele envia uma tarefa de imagem para gpt-image-2 e imprime o id da tarefa:

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": "uma única maçã vermelha sobre uma mesa de madeira, luz do dia suave",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Resposta esperada:

200 com {"id":"task_...","status":"queued"} → chave OK, cota OK.
429 com {"error":{"code":"rate_limit_exceeded",...}} → você excedeu o limite de RPM, RPD ou concorrência. Reduza a velocidade conforme os passos de correção acima.
401 com {"error":{"code":"permission_denied",...}} → falha de autenticação, não limite de taxa. Verifique sua chave.

Repita essa chamada com um loop rápido de seq 1 10 | xargs -n1 -P10 curl ... para encontrar seu limite de concorrência — o primeiro que retornar 429 marca seu limite efetivo.

Leitura relacionada

Diagnóstico de travamentos e timeouts de tarefas na HiAPI — quando uma tarefa fica nos estados queued ou processing por mais tempo que o esperado.
Por que o callback da sua tarefa HiAPI não disparou — diagnóstico de callbacks assíncronos no fluxo /v1/tasks.
Resolvendo o erro model_not_available — categoria de erro vizinha, frequentemente mal interpretada como limite de taxa.
Catálogo de modelos — preços e tipos de endpoint por modelo.
Preços — detalhamento por nível.

Perguntas frequentes

Existe um valor público de RPM para gpt-image-2 na HiAPI? Os limites dependem do nível e podem mudar conforme os provedores ajustam seus respectivos tetos. Consulte seu painel para obter o limite efetivo atual, em vez de fixar no código números de um artigo de blog.

Por que as novas tentativas às vezes pioram o 429? Usar ingenuamente sleep(1) para novas tentativas em N workers paralelos transforma um 429 em N novas tentativas sincronizadas, todas atingindo o limite novamente. Use jitter completo (sleep * random.random()) em vez de um atraso fixo.

A HiAPI cobra por respostas 429? Não. Criações de tarefas que falham (429, 401, 4xx em geral) não são cobradas. Você paga apenas por tarefas que geram saída com sucesso.

Aumentar a concorrência no cliente eleva meu limite? Não. O limite de concorrência é definido no servidor por chave. O paralelismo do cliente só determina se você fica abaixo do limite ou o aciona.

Qual é a diferença entre RPM e TPM? As APIs de imagem limitam por solicitação (RPM), não por token (TPM) — tarefas de imagem não têm uma unidade significativa de "token". Se você vir um limite de TPM no painel, ele se aplica aos endpoints de texto/chat, não às tarefas de imagem de /v1/tasks.

Devo usar uma chave de alta concorrência ou várias chaves de baixa concorrência? Para cargas de trabalho de imagem, uma chave por pool lógico de trabalho é o modelo mental mais simples. Várias chaves sob uma conta de cobrança não multiplicam sua cota na prática — elas compartilham a cota.

Posso solicitar um limite de concorrência maior? Sim — depois de demonstrar uso contínuo no seu nível atual. Envie à equipe de suporte o request_id de um 429 representativo, e eles poderão rastrear qual dimensão você atingiu.

Por que não vejo o cabeçalho Retry-After? Nem todos os provedores o enviam. Quando ausente, use backoff exponencial com jitter começando em 1s. Quando presente, essa nova tentativa deve confiar nele.