Skip to main content
Requisições como geração de vídeo e geração de imagens em lote costumam levar mais tempo do que é razoável esperar em uma única conexão HTTP. Além disso, se o cliente se desconectar durante a geração de textos longos, a resposta já produzida também não pode mais ser recuperada. As tarefas assíncronas (Async Tasks) unificam esses três cenários em um mesmo objeto de tarefa: imagens e vídeos criam a tarefa pela interface de geração e retornam imediatamente o task_id, enquanto requisições de LLM interrompidas pelo cliente são concluídas pela plataforma, que salva a resposta final. Os três compartilham os mesmos status de tarefa, a mesma interface de consulta e o mesmo fluxo de download de resultados.
Use a mesma API Key com que a tarefa foi criada para consultar a tarefa e baixar os resultados. As tarefas são isoladas por API Key: mesmo que duas Keys pertençam à mesma conta, uma não pode ler as tarefas da outra.

Acessar o console para ativar as tarefas assíncronas

Antes de criar imagens ou vídeos assíncronos, ative o recurso de tarefas assíncronas para a conta atual. Se o console ainda não exibir esse acesso, entre em contato com o suporte técnico da AIHubMix.
Quando o recurso de tarefas assíncronas não está ativado, as requisições de criação de tarefas de mídia retornam 403 async_not_enabled. As requisições de LLM não geram erro por causa disso, mas a resposta final não pode ser recuperada depois que o cliente se desconecta.

1. Início rápido

O fluxo completo das tarefas assíncronas de imagem e vídeo tem três etapas:

2. Comparação: chamadas síncronas vs tarefas assíncronas

Uma chamada síncrona retorna o resultado dentro de uma única resposta HTTP e o resultado não pode ser recuperado se a conexão cair. As tarefas assíncronas mantêm o resultado no lado da plataforma, e o task_id permite consultar e baixar novamente com a mesma API Key antes de o resultado expirar. Isso serve para requisições de geração demoradas e para saídas de texto longo cuja resposta final precisa ser recuperada após uma interrupção.

3. Visão geral das interfaces

Base URL: https://aihubmix.com, com autenticação por Bearer Token:
/ai/v1/tasks é um ponto de consulta unificado somente leitura e não oferece POST /ai/v1/tasks. Imagens e vídeos são criados pelas respectivas interfaces de geração; as requisições que atendem às condições de recuperação de interrupção de LLM são registradas automaticamente como tarefas llm após a desconexão do cliente.

4. Modelos suportados

As tarefas assíncronas dividem a cobertura por tipo de tarefa e não exigem parâmetros adicionais na chamada.

4.1 Imagem assíncrona

4.2 Vídeo assíncrono

4.3 Recuperação de interrupção de LLM

A cobertura será ampliada continuamente e esta tabela será atualizada junto.

5. Como criar uma tarefa assíncrona

5.1 Imagem assíncrona

A interface de imagens retorna de forma síncrona por padrão. Com async definido como true, a interface retorna imediatamente o objeto de tarefa e o processo de geração continua em segundo plano.
async deve ser um valor booleano. Se não for enviado ou for definido como false, a interface de imagens mantém o comportamento síncrono.

5.2 Vídeo assíncrono

A interface de vídeo é sempre assíncrona. Após a criação bem-sucedida, ela retorna o status pending ou in_progress e não permite mudar para espera síncrona com Prefer: wait.

5.3 Parâmetros comuns

Nos exemplos, model, prompt, n, seconds e size são parâmetros de modelo comuns. Os campos e valores aceitos por cada modelo seguem a documentação de API do modelo correspondente; para modelos de vídeo, consulte a documentação de geração de vídeo. A tabela abaixo descreve apenas os parâmetros compartilhados por todas as tarefas assíncronas.
Tarefas de imagem só podem usar Webhook quando têm async: true. Ao omitir webhook_events_filter, a plataforma envia os três estados finais completed, failed e cancelled; quando informado, ele deve ser usado junto com webhook_url e não pode ser vazio nem conter valores repetidos.

6. Como funciona a recuperação de interrupção de LLM

A recuperação de interrupção de LLM serve para recuperar a resposta final depois que o cliente se desconecta. Esse recurso reutiliza a forma atual de fazer requisições de LLM, mantém o comportamento de streaming e o formato de resposta, não exige a chamada de uma interface de criação adicional e não retorna um task_id antecipadamente.

6.1 Condições de funcionamento

As condições abaixo devem ser atendidas ao mesmo tempo: Interfaces suportadas:
Nenhum campo adicional precisa ser enviado na chamada. A cobertura está em 4.3 Recuperação de interrupção de LLM; para modelos não listados na tabela, faça a validação da recuperação de interrupção com uma requisição de baixo custo antes da integração oficial, e a requisição de validação continua sendo cobrada normalmente. Se alguma das condições não for atendida, a requisição continua sendo executada normalmente e nenhuma tarefa llm é gerada após a desconexão do cliente.

6.2 Fluxo de execução após a interrupção

Requisições de LLM concluídas normalmente e entregues com sucesso ao cliente não criam tarefas e não aparecem na lista de tarefas. As requisições interrompidas aparecem na lista depois que a resposta final termina de ser salva, portanto podem ficar temporariamente indisponíveis para consulta durante o processamento.

6.3 Localizar a requisição interrompida correspondente

O cabeçalho de resposta do LLM retorna X-Aihubmix-Request-Id. Assim que receber os cabeçalhos de resposta, o cliente deve salvar esse valor; após uma interrupção, é possível usar esse ID de requisição para localizar a tarefa correspondente na lista de tarefas assíncronas do console da AIHubMix. A API pública de tarefas ainda não permite filtrar por ID de requisição. Sem o ID de requisição salvo, a busca só pode ser feita por modelo e horário de criação, usando a mesma API Key da requisição original:
Quando a mesma API Key envia várias requisições simultâneas para o mesmo modelo, apenas o modelo e o horário de criação não garantem a correspondência exata. Para uma recuperação confiável, salve o X-Aihubmix-Request-Id e faça a busca pelo console; se os cabeçalhos de resposta não tiverem sido obtidos, evite tratar a tarefa mais recente da lista diretamente como a requisição em questão.
As tarefas de recuperação de interrupção de LLM ainda não enviam Webhook; consulte o resultado pela lista de tarefas. A interrupção do cliente não impede que a plataforma continue processando a requisição, e essa chamada continua sendo cobrada segundo as regras da interface de LLM original.

7. Objeto de tarefa e status

Todas as tarefas usam uma estrutura de resposta unificada:
Campos dos resultados em output:

7.1 Descrição dos status

Recomenda-se consultar a cada 15 segundos, até o status mudar para completed, failed ou cancelled.
Tarefas com status failed ou cancelled também podem conter resultados parciais já gerados. Ao verificar se há resultados, além do status, confira também se output está vazio.

8. Como consultar tarefas

8.1 Consultar os detalhes da tarefa

Essa interface retorna as informações mais recentes da tarefa no momento da consulta. A operação de consulta não altera a tarefa; o status é atualizado automaticamente pela plataforma.

8.2 Consultar a lista de tarefas

Quando a resposta de criação for perdida, ou quando for preciso revisar várias tarefas anteriores, o task_id pode ser recuperado pela interface de lista:
Exemplo de resposta:
Para solicitar a próxima página:

9. Como obter o resultado da tarefa

9.1 Tarefas com um único arquivo

Quando output tem apenas um arquivo, o acesso pode ser direto:
Também é possível usar diretamente output[0].content_url. O Content-Type da resposta de download é igual a output[0].content_type.

9.2 Tarefas com múltiplos arquivos

Quando output contém vários arquivos, é obrigatório indicar o result_id correspondente:
Se o result_id não for informado em uma tarefa com múltiplos arquivos, a interface retorna 400 result_id_required.

9.3 Tarefas de resposta de LLM

Depois que as condições de recuperação de interrupção de LLM são atendidas e a resposta é salva, o object da tarefa é llm e o type do item de output é response. O tipo de conteúdo pode ser:
  • application/json: resposta JSON comum
  • text/event-stream: resposta em streaming SSE salva
A marcação de truncamento fica em output[0].truncated, nos detalhes da tarefa. O valor true indica que a resposta salva foi truncada por limite de tamanho. GET /ai/v1/tasks/{task_id}/content retorna o conteúdo JSON ou SSE original, sem envolver o conteúdo em um campo truncated, portanto consulte primeiro os detalhes da tarefa e depois leia o conteúdo.
Os resultados podem expirar e também pode haver limite no número de downloads. Salve os arquivos antes de expires_at. Após a expiração, é retornado 410 artifact_expired; ao ultrapassar o limite de downloads, é retornado 429 too_many_downloads.

10. Como usar Webhook

Atualmente é possível informar um Webhook por tarefa no momento da criação da tarefa assíncrona. Para que a AIHubMix notifique ativamente após a conclusão da tarefa, envie webhook_url e o opcional webhook_events_filter no corpo da requisição de imagem ou vídeo assíncrona:
O endereço de callback deve usar HTTPS e não pode apontar para o próprio host, para redes privadas ou para outros endereços restritos.

10.1 Requisição de callback

A AIHubMix envia uma requisição POST ao endereço de callback:
As URLs em results ainda exigem a API Key usada na criação da tarefa para serem acessadas.

10.2 Novas tentativas e deduplicação

A plataforma tenta entregar o callback pelo menos uma vez, portanto o mesmo evento pode ser enviado mais de uma vez:
  • HTTP 2xx indica recebimento bem-sucedido.
  • HTTP 5xx, erros de rede ou timeouts acionam novas tentativas.
  • HTTP 3xx e 4xx não geram novas tentativas.
  • No máximo 6 entregas, com intervalos de 1, 4, 16, 64 e 256 segundos.
O receptor deve armazenar o event_id. Ao receber novamente o mesmo event_id, pule a lógica de negócio e retorne 2xx diretamente.
O Webhook por tarefa atual não oferece credenciais de assinatura independentes configuráveis. Ao receber a notificação, use a API Key da criação da tarefa para chamar GET /ai/v1/tasks/{task_id} e considere o resultado da consulta como definitivo.

11. Respostas de erro e códigos de erro

As respostas de erro usam uma estrutura unificada:

12. Exemplo completo

Fluxo completo para criar uma tarefa de vídeo, fazer polling do status e baixar todos os resultados:

Perguntas frequentes (FAQ)

Com que frequência devo consultar o status da tarefa? Recomenda-se consultar a cada 15 segundos, evitando polling de alta frequência. Ao usar Webhook, mantenha também uma consulta de baixa frequência como alternativa. Como recuperar a tarefa depois de perder a resposta de criação? Use a mesma API Key da criação da tarefa para chamar GET /ai/v1/tasks, restringindo a busca por object, model e status. Por que outra API Key da mesma conta não encontra a tarefa? As tarefas são isoladas por API Key. As requisições de consulta, download e listagem devem usar a mesma Key com que a tarefa foi criada. Por que a tarefa falhou, mas output não é um array vazio? Alguns modelos podem já ter gerado resultados entregáveis antes da falha ou do cancelamento geral. Sempre que houver content_url ou b64_json em output, o resultado pode ser obtido pelo método correspondente. O que fazer se o Webhook não chegar? Verifique se o endereço de callback é publicamente acessível, se usa HTTPS e se retorna 2xx em até 10 segundos. Com ou sem Webhook, o status final sempre pode ser consultado por GET /ai/v1/tasks/{task_id}. A recuperação de interrupção de LLM exige mudanças no código atual? Não. A forma de fazer a requisição, o comportamento de streaming e o formato da resposta permanecem iguais. Recomenda-se salvar o cabeçalho de resposta X-Aihubmix-Request-Id para localizar a tarefa correspondente com precisão no console após uma interrupção.
Data de atualização: 2026-07-28