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.
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. Comasync 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 statuspending 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 umtask_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
6.3 Localizar a requisição interrompida correspondente
O cabeçalho de resposta do LLM retornaX-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:
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
8.2 Consultar a lista de tarefas
Quando a resposta de criação for perdida, ou quando for preciso revisar várias tarefas anteriores, otask_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
Quandooutput tem apenas um arquivo, o acesso pode ser direto:
output[0].content_url. O Content-Type da resposta de download é igual a output[0].content_type.
9.2 Tarefas com múltiplos arquivos
Quandooutput contém vários arquivos, é obrigatório indicar o result_id correspondente:
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, oobject da tarefa é llm e o type do item de output é response. O tipo de conteúdo pode ser:
application/json: resposta JSON comumtext/event-stream: resposta em streaming SSE salva
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.
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, enviewebhook_url e o opcional webhook_events_filter no corpo da requisição de imagem ou vídeo assíncrona:
10.1 Requisição de callback
A AIHubMix envia uma requisiçãoPOST 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
2xxindica recebimento bem-sucedido. - HTTP
5xx, erros de rede ou timeouts acionam novas tentativas. - HTTP
3xxe4xxnão geram novas tentativas. - No máximo 6 entregas, com intervalos de 1, 4, 16, 64 e 256 segundos.
event_id. Ao receber novamente o mesmo event_id, pule a lógica de negócio e retorne 2xx diretamente.
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 chamarGET /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