Tarefas assíncronas

A AIHubMix oferece três grupos de APIs de tarefas: /ai/v1/images para imagens, /ai/v1/videos para vídeos e /ai/v1/tasks para registros unificados de tarefas.

A geração de imagens é síncrona por padrão e se torna assíncrona com async: true.
A geração de vídeos é sempre assíncrona.
As APIs de detalhes de imagens e vídeos fornecem o status mais recente das tarefas de mídia.
/ai/v1/tasks fornece uma visão unificada somente leitura das tarefas de imagem, vídeo e LLM.

Para referenciar materiais de pessoas reais em vídeos Doubao Seedance, siga o guia de uso de materiais de pessoas reais no Doubao para concluir a confirmação pessoal e preparar os materiais antes de criar a tarefa de vídeo.

Tutorial em vídeo: tarefas assíncronas

Explica o funcionamento geral das tarefas assíncronas e demonstra o fluxo completo de chamadas usando a geração assíncrona de imagens como exemplo.

Ativar tarefas assíncronas no console

Antes de usar as APIs de tarefas de mídia /ai/v1, ative as tarefas assíncronas para a conta atual.

Se as tarefas assíncronas não estiverem ativadas, as requisições de criação de imagens e vídeos retornarão 403 async_not_enabled.

Início rápido

O exemplo a seguir cria um vídeo com wan2.6-t2v. Esse modelo aceita duration e size. Os campos válidos podem variar conforme o modelo.

# 1. Criar a tarefa de vídeo e salvar o id da resposta
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
    "duration": 5,
    "size": "1280x720"
  }'

# 2. Consultar os detalhes da mídia a cada 15 segundos
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3. Baixar o vídeo quando o status for completed
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

Como escolher entre os três grupos de APIs

Caso de uso	Método	Caminho	Comportamento
Gerar imagem	POST	`/ai/v1/images/generations`	Síncrona por padrão, assíncrona com `async: true`
Consultar detalhes da imagem	GET	`/ai/v1/images/{id}`	Retorna o status; tarefas ativas podem ter o status atualizado durante a consulta
Listar imagens	GET	`/ai/v1/images`	Retorna um instantâneo das tarefas de imagem
Baixar uma imagem específica	GET	`/ai/v1/images/{id}/content/{result_id}`	Baixa um resultado específico de uma tarefa com várias imagens
Criar vídeo	POST	`/ai/v1/videos`	Sempre assíncrona
Consultar detalhes do vídeo	GET	`/ai/v1/videos/{id}`	Retorna o status; tarefas ativas podem ter o status atualizado durante a consulta
Listar vídeos	GET	`/ai/v1/videos`	Retorna um instantâneo das tarefas de vídeo
Baixar vídeo	GET	`/ai/v1/videos/{id}/content`	Baixa o resultado principal de vídeo da tarefa
Listar modelos de mídia assíncronos	GET	`/api/v1/models?type={type}&schema_checked=true`	Retorna modelos de texto para imagem ou texto para vídeo com esquema de solicitação
Obter o esquema de solicitação do modelo	GET	`/call/schema/models/{model}/endpoints`	Retorna endpoints de texto para imagem ou texto para vídeo e seus esquemas JSON
Listar tarefas unificadas	GET	`/ai/v1/tasks`	Consulta somente leitura de tarefas de imagem, vídeo e LLM
Consultar tarefa unificada	GET	`/ai/v1/tasks/{id}`	Retorna um instantâneo somente leitura no momento da consulta
Obter resultado de tarefa unificada	GET	`/ai/v1/tasks/{id}/content`	Baixa um único resultado ou lê uma resposta LLM arquivada
Obter resultado unificado específico	GET	`/ai/v1/tasks/{id}/content/{result_id}`	Baixa um resultado específico de uma tarefa com vários resultados

A Base URL é https://aihubmix.com. A autenticação usa Bearer Token:

Authorization: Bearer $AIHUBMIX_API_KEY

Os endpoints de lista de modelos e de esquema de modelos são públicos e não exigem Bearer Token. Os demais endpoints exigem autenticação.

/ai/v1/tasks não oferece uma API de criação. Imagens e vídeos devem ser criados pelas APIs de geração de mídia correspondentes. As tarefas de recuperação de LLM são salvas automaticamente pela plataforma após a interrupção do cliente.

Diferenças entre as APIs de mídia e de tarefas unificadas

As APIs de detalhes de mídia e de tarefas unificadas retornam os mesmos campos de nível superior, mas os itens de output e o comportamento de consulta são diferentes.

Item comparado	Detalhes de mídia `/images/{id}`, `/videos/{id}`	Detalhes unificados `/tasks/{id}`
Tipo de tarefa	Imagem ou vídeo	Imagem, vídeo ou LLM
Comportamento da consulta	Tarefas ativas podem ter o status atualizado	Retorna um instantâneo somente leitura no momento da consulta
Campos de saída de mídia	`index`, `type`, `content_url`, `b64_json`	`index`, `result_id`, `type`, `content_type`, `content_url`
Campos de saída de LLM	Não se aplica	`index`, `type=response`, `content_type`, `content_url`, `truncated`
Escopo de acesso	Tarefas de mídia correspondentes criadas pela conta atual	Tarefas criadas pelo Bearer Token atual

Para acompanhar o status de uma geração de mídia, use a API de detalhes de imagem ou vídeo. Para filtrar tarefas de forma unificada, ler metadados de resultados ou recuperar uma resposta LLM, use /ai/v1/tasks.

Como descobrir modelos de mídia assíncronos e obter seus esquemas

O fluxo de descoberta tem duas etapas. Primeiro, obtenha no catálogo público os modelos de texto para imagem ou texto para vídeo compatíveis com as APIs assíncronas. Depois, use o model_id do modelo para obter o esquema de solicitação de seus endpoints.

Listar modelos compatíveis com as APIs assíncronas

O catálogo de modelos usa a mesma fonte de dados do Playground. Use type=image_generation para modelos de texto para imagem e type=video para modelos de texto para vídeo. Com schema_checked=true, a lista fica limitada a modelos cujo esquema de solicitação foi publicado e revisado.

# Modelos de texto para imagem
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# Modelos de texto para vídeo
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

As duas solicitações usam o mesmo endpoint. O filtro type aceita atualmente um único valor, então solicite cada tipo de modelo separadamente. A resposta tem o formato {success, message, data}. Os campos de data relevantes para integrações de mídia assíncrona são os seguintes.

Campo	Descrição
`data[].model_id`	ID do modelo usado na geração e nas solicitações posteriores de esquema
`data[].model_name`	Nome de exibição do modelo
`data[].types`	Tipos separados por vírgulas, podendo incluir `image_generation` e `llm`
`data[].input_modalities`	Modalidades de entrada separadas por vírgulas
`data[].schema_checked`	`true` quando o esquema de solicitação foi publicado e revisado

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

Obter o esquema de solicitação de um modelo

Os campos, enumerações e intervalos numéricos aceitos podem variar conforme o modelo. Antes de enviar uma solicitação de imagem ou vídeo, use o endpoint público abaixo para obter os endpoints disponíveis e os esquemas JSON de solicitação do modelo selecionado.

# Modelo de texto para imagem
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# Modelo de texto para vídeo
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

O valor de modality na resposta é image ou video. Cada item do array endpoints descreve um protocolo de chamada disponível.

Campo	Descrição
`default_endpoint`	Identificador do endpoint padrão do modelo
`endpoints[].endpoint`	Identificador do endpoint
`endpoints[].method`	Método HTTP, como `POST`
`endpoints[].path`	Caminho da solicitação
`endpoints[].content_types`	Tipos de conteúdo aceitos pelo endpoint
`endpoints[].lifecycle`	Modo síncrono ou assíncrono, caminho de consulta e valores de status
`endpoints[].request.schema`	Esquema JSON completo da solicitação para este modelo e endpoint, incluindo campos obrigatórios e restrições de valores

Um modelo pode retornar endpoints /ai/v1 e endpoints /v1 compatíveis com OpenAI. Os endpoints compatíveis com OpenAI podem ainda não oferecer suporte aos modelos mais recentes, portanto dê preferência aos endpoints /ai/v1. Para as APIs de tarefas assíncronas, selecione o item cujo path seja /ai/v1/images/generations ou /ai/v1/videos e use seu request.schema. Não dependa da posição do item no array endpoints. Os comandos abaixo extraem diretamente o esquema de solicitação de cada endpoint de tarefa assíncrona.

# Texto para imagem
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# Texto para vídeo
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

O endpoint retorna 404 model_not_found quando o modelo não existe ou não possui endpoints detectáveis. Ele retorna 500 endpoints_unavailable quando os dados dos endpoints estão temporariamente indisponíveis.

Modelos e campos compatíveis

Os protocolos de imagem e vídeo definem campos padrão entre modelos, mas cada modelo restringe campos, enumerações e intervalos numéricos conforme seus recursos. Antes da chamada, obtenha as restrições atuais no endpoint de esquema do modelo. Por exemplo:

wan2.6-t2v aceita duration, size e seed, mas não aceita resolution, aspect_ratio, frame_images, input_references nem generate_audio.
qwen-image-2.0 aceita n, size, seed, negative_prompt, image e images, mas não aceita aspect_ratio nem mask.

O conjunto de campos padrão não significa que todos os modelos aceitam todos os campos. Enviar um campo não aceito pelo modelo atual retorna um erro de parâmetro.

Modelos para recuperação de interrupção de LLM

Atualmente, os seguintes modelos são compatíveis:

gpt-5.6-sol
gpt-5.5-pro
gpt-5.4-pro
gpt-5.2-pro
claude-fable-5
claude-opus-5

O escopo pode mudar. Consulte a lista desta página. A recuperação também exige que as tarefas assíncronas estejam ativadas para a conta atual. Se qualquer uma dessas condições não for atendida, a requisição LLM original continuará funcionando normalmente, mas nenhuma tarefa de recuperação será salva após a desconexão do cliente.

Como criar uma tarefa de imagem

Imagem síncrona

Quando async é omitido ou definido como false, a API aguarda a conclusão da geração e retorna o objeto de tarefa:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

As tarefas síncronas de imagem também são registradas. Se a conexão do cliente for interrompida ou a resposta de criação for perdida, use GET /ai/v1/images para localizar a tarefa.

Imagem assíncrona

Quando async é definido como o booleano true, a API retorna imediatamente o objeto de tarefa e a geração continua em segundo plano:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

Consulte a tarefa assíncrona de imagem com GET /ai/v1/images/{id}. Após a conclusão, solicite diretamente o content_url de cada item de output. Essa URL já contém o result_id da imagem correspondente.

O campo async de uma requisição de imagem deve ser booleano. webhook_url e webhook_events_filter só podem ser usados com async: true.

Campos padrão de imagem

Campo	Tipo	Obrigatório	Descrição
`model`	string	Sim	Nome do modelo
`prompt`	string	Sim	Descrição da imagem, não pode estar vazia
`n`	integer/null	Não	Quantidade de imagens, mínimo `1`, padrão `1`
`size`	string/null	Não	`{width}x{height}`, por exemplo `1024x1024`
`aspect_ratio`	string/null	Não	Proporção da imagem, mutuamente exclusiva com `size`
`seed`	integer/null	Não	Semente aleatória
`negative_prompt`	string/null	Não	Prompt negativo
`image`	string/object	Não	Uma imagem de entrada como URL, Data URI, Base64 ou objeto `{url}`
`images`	array/null	Não	Várias imagens de entrada
`mask`	string/object	Não	Máscara para edição de imagem
`output_format`	string/null	Não	`png`, `jpeg` ou `webp`, padrão `png`
`response_format`	string/null	Não	`url` ou `b64_json`, padrão `url`
`async`	boolean	Não	Executa de forma assíncrona quando definido como `true`
`webhook_url`	string	Não	Endereço HTTPS de callback, máximo de 512 caracteres
`webhook_events_filter`	string[]	Não	Subconjunto não vazio de `completed`, `failed`, `cancelled`
`extra`	object/null	Não	Parâmetros estendidos específicos do modelo

Como criar uma tarefa de vídeo

As requisições de vídeo são sempre assíncronas e não aceitam Prefer: wait para aguardar de forma síncrona. O protocolo padrão usa o inteiro duration em segundos:

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'

Campos padrão de vídeo

Campo	Tipo	Obrigatório	Descrição
`model`	string	Sim	Nome do modelo
`prompt`	string	Sim	Descrição do vídeo, não pode estar vazia
`duration`	integer/null	Não	Duração do vídeo em segundos, intervalo definido pelo modelo
`aspect_ratio`	string/null	Não	Proporção do vídeo, padrão do protocolo `16:9`
`resolution`	string/null	Não	`480p`, `720p`, `1080p`, `1K`, `2K` ou `4K`
`size`	string/null	Não	`{width}x{height}`, pode substituir `resolution` e `aspect_ratio`
`seed`	integer/null	Não	Semente aleatória
`input_references`	array/null	Não	Materiais de referência de imagem, vídeo ou áudio
`frame_images`	array/null	Não	Imagem do primeiro ou do último frame
`generate_audio`	boolean/null	Não	Indica se uma faixa de áudio deve ser gerada
`webhook_url`	string	Não	Endereço HTTPS de callback, máximo de 512 caracteres
`webhook_events_filter`	string[]	Não	Subconjunto não vazio de `completed`, `failed`, `cancelled`
`extra`	object/null	Não	Parâmetros estendidos específicos do modelo

Estrutura de um item de input_references:

{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}

type pode ser image_url, video_url ou audio_url. Estrutura de um item de frame_images:

{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}

frame_type pode ser first_frame ou last_frame.

Objeto de tarefa de mídia

As APIs específicas de imagem e vídeo retornam a seguinte estrutura:

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}

Campo	Tipo	Descrição
`id`	string	ID de tarefa da plataforma
`object`	string	`image` ou `video`
`model`	string	Nome do modelo
`status`	string	Status atual da tarefa
`output`	array	Resultados gerados, ou um array vazio quando ainda não há resultados
`error`	object/null	Informações da falha, podendo conter `code`, `message` e `upstream_detail`
`created_at`	integer	Data de criação em segundos Unix
`completed_at`	integer/null	Data do status final em segundos Unix
`expires_at`	null	As APIs específicas de mídia atualmente retornam `null`

Item de output de mídia:

Campo	Tipo	Descrição
`index`	integer	Ordem do resultado, começando em `0`
`type`	string	Atualmente é `file`
`content_url`	string/null	Endereço de download do resultado
`b64_json`	string/null	Resultado de imagem codificado em Base64

Descrição dos status

Status	Final	Descrição
`pending`	Não	A plataforma recebeu a tarefa e aguarda a execução
`in_progress`	Não	A tarefa está em execução
`completed`	Sim	Tarefa concluída, `output` disponível
`failed`	Sim	A tarefa falhou, consulte `error`
`cancelled`	Sim	A tarefa foi cancelada

O cliente pode consultar a tarefa a cada 15 segundos até que o status seja completed, failed ou cancelled. Esse intervalo de 15 segundos é uma recomendação de polling do cliente, não uma limitação do protocolo do servidor.

Como consultar tarefas de mídia

Consultar detalhes da mídia

# Imagem
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Vídeo
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

As APIs de detalhes de mídia podem retornar um status atualizado. Por isso, use a API de detalhes da imagem ou do vídeo correspondente para fazer polling.

Consultar a lista de mídia

Se a resposta de criação for perdida, localize o ID da tarefa na lista da mídia correspondente:

curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Parâmetro	Tipo	Padrão	Descrição
`after`	string	-	Cursor de paginação, use o `next_after` da página anterior
`limit`	integer	`20`	Quantidade por página, máximo `100`
`order`	string	`desc`	`asc` para ordem crescente; outros valores são tratados como `desc`

{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}

A lista de mídia retorna um instantâneo da tarefa no momento da consulta e não atualiza ativamente o status.

Como usar a API de tarefas unificadas

A API de tarefas unificadas aceita os seguintes filtros:

curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Parâmetro	Tipo	Padrão	Descrição
`object`	string	-	`llm`, `image` ou `video`
`status`	string	-	`pending`, `in_progress`, `completed`, `failed` ou `cancelled`
`model`	string	-	Filtro exato pelo nome do modelo
`after`	string	-	Cursor de paginação
`limit`	integer	`20`	Intervalo de `1` a `100`
`order`	string	`desc`	`asc` ou `desc`

Detalhes da tarefa unificada:

curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Item de output unificado de uma tarefa de mídia:

{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}

Para um único resultado, solicite diretamente /ai/v1/tasks/{id}/content. Para tarefas com vários resultados, solicite /ai/v1/tasks/{id}/content/{result_id}. Sem o ID do resultado, a API retorna 400 result_id_required.

As APIs de lista, detalhes e conteúdo das tarefas unificadas são isoladas pelo Bearer Token usado para criar a tarefa. Outra API Key da mesma conta não pode ler essa tarefa.

Como baixar resultados de mídia

Baixar imagens

Quando a imagem estiver concluída, solicite cada output[].content_url do objeto de tarefa de mídia:

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

O caminho de download de mídia da imagem é /ai/v1/images/{id}/content/{result_id}. O objeto de tarefa de mídia não expõe result_id separadamente. O cliente pode usar content_url diretamente. Quando b64_json não estiver vazio, decodifique esse campo diretamente em Base64.

Baixar vídeo

curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

Os resultados podem expirar e podem ter limite de downloads. Um resultado expirado retorna 410 artifact_expired. Exceder o limite de downloads retorna 429 too_many_downloads.

Como usar Webhook

Imagens assíncronas e vídeos aceitam Webhooks no nível da tarefa:

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil garden at sunrise",
    "duration": 5,
    "size": "1280x720",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'

webhook_url aceita no máximo 512 caracteres e não pode apontar para a máquina local, uma rede privada ou outro endereço restrito. Quando webhook_events_filter é omitido, a plataforma envia completed, failed e cancelled. Quando informado explicitamente, o array não pode estar vazio nem conter duplicatas e deve ser usado com webhook_url. Quando webhook_url não é enviado na requisição, imagens assíncronas e vídeos tentam usar o endereço de callback padrão configurado na conta. Um endereço padrão inválido é ignorado e não impede a criação da tarefa.

Requisição de callback

{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}

Campo	Descrição
`event_id`	ID do evento de callback, usado para desduplicação
`event_type`	`completed`, `failed` ou `cancelled`
`created_at`	Data e hora do evento no formato RFC 3339
`data.task_id`	ID de tarefa da plataforma
`data.status`	Status final atual
`data.model`	Nome do modelo
`data.results[].url`	Endereço de download que pode ser retornado na conclusão
`data.error`	Informações de erro que podem ser retornadas em caso de falha

results só aparece quando o resultado foi arquivado. O download ainda exige um Bearer Token.

Novas tentativas e desduplicação

A plataforma usa entrega pelo menos uma vez. O mesmo evento pode ser enviado mais de uma vez:

HTTP 2xx indica recebimento bem-sucedido.
HTTP 5xx, erros de rede ou timeout acionam uma nova tentativa.
HTTP 3xx e 4xx não acionam novas tentativas.
São feitas no máximo 6 entregas, com intervalos de 1, 4, 16, 64 e 256 segundos.

O destinatário deve salvar event_id e retornar imediatamente 2xx ao receber novamente o mesmo evento.

O Webhook no nível da tarefa não possui uma chave de assinatura independente. Se precisar verificar a assinatura, configure uma assinatura de Webhook no nível da conta e mantenha a consulta dos detalhes da tarefa como forma de confirmar o resultado.

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

A recuperação de interrupção de LLM permite obter a resposta final após a desconexão do cliente. O formato da requisição, o comportamento de streaming e o formato da resposta não mudam. Nenhum ID de tarefa é retornado antecipadamente no início da requisição. As condições abaixo devem ser atendidas ao mesmo tempo:

Condição	Descrição
Tarefas assíncronas ativadas para a conta	Ative para a conta atual no console da AIHubMix
Modelo compatível com recuperação	O modelo atual está na lista de modelos para recuperação de interrupção de LLM
API compatível	Chat Completions, Anthropic Messages, Responses API ou Gemini `generateContent` / `streamGenerateContent`
Interrupção do cliente	Cancelamento pelo cliente, desconexão de rede ou cancelamento da requisição pelo chamador

A plataforma só cria uma tarefa de recuperação e salva o JSON ou SSE final quando detecta que a resposta não foi entregue por completo e o cliente se desconectou. Uma requisição LLM concluída normalmente e entregue integralmente ao cliente não cria uma tarefa de recuperação. Os cabeçalhos de resposta de LLM incluem X-Aihubmix-Request-Id. O cliente deve salvar esse valor o quanto antes para localizar a requisição correspondente no console. Atualmente, a API pública de tarefas não permite filtrar pelo ID da requisição. É possível consultar as tarefas LLM recentes por modelo e data de criação:

curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

O item de output unificado de uma tarefa LLM contém type=response, content_type, content_url e truncated. GET /ai/v1/tasks/{id}/content retorna o JSON ou SSE original salvo.

Atualmente, as tarefas de recuperação de interrupção de LLM não enviam Webhooks no nível da tarefa. A interrupção do cliente não interrompe o processamento da requisição pela plataforma. A chamada continua sendo cobrada conforme as regras da API original.

Respostas e códigos de erro

Esta seção se aplica a /ai/v1/images/*, /ai/v1/videos/* e às tarefas de mídia com object=image ou object=video em /ai/v1/tasks/*. O cliente deve tratar tanto respostas HTTP não 2xx quanto o estado terminal HTTP 200 com status=failed.

{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

Enviar feedback sobre erros HTTP 5xx

Se a requisição retornar HTTP 5xx, envie feedback e inclua error.tid.

Erros HTTP não 2xx

As linhas invalid_request e schema_violation mostram mensagens de fallback. Quando o serviço consegue identificar um campo ou uma restrição, ele retorna um message dinâmico; o cliente deve usar code para classificar o erro e não comparar message com um texto fixo.

HTTP	`code`	`message`	Descrição
400	`invalid_request`	`Invalid request. Check the request body and parameters.` (mensagem de fallback; a mensagem real pode ser dinâmica)	O corpo comum, os tipos de campo ou os parâmetros de listagem são inválidos; o `message` deste `code` não é fixo e pode incluir detalhes dinâmicos quando o campo é conhecido.
400	`model_not_found`	`The requested model is not available. Check the model name and your account access.`	O modelo não existe, não está disponível ou a conta não possui acesso.
400	`schema_violation`	`Invalid request: one or more parameters are invalid.` (mensagem de fallback; a mensagem real pode ser dinâmica)	A requisição não atende ao Schema de parâmetros do modelo; o `message` deste `code` não é fixo e pode identificar dinamicamente o campo ou a restrição.
400	`capability_not_supported`	`The requested parameters are not supported for this model.`	O modelo não aceita um campo, uma quantidade ou um limite solicitado.
400	`media_form_unsupported`	Mensagem dinâmica de mídia; consulte a tabela abaixo.	Não foi possível processar o formato, os dados, a URL ou o tamanho de uma imagem, vídeo, referência ou quadro inicial/final.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	A tarefa possui vários resultados e o download não informou `result_id`.
400	`upstream_rejected`	`Upstream service rejected the request.`	O provedor de modelos de inferência rejeitou a requisição de criação.
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	A API Key está ausente ou é inválida.
402	`insufficient_quota`	`Insufficient quota.`	A conta AIHubMix não possui saldo disponível suficiente.
403	`permission_denied`	`You do not have permission to access this resource.`	A conta, a API Key ou a origem de acesso não possuem permissão para usar o recurso.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to <console-url>/async-tasks to activate.`	A conta não possui tarefas assíncronas ativadas; a URL do console depende do site da requisição.
404	`task_not_found`	`Task not found.`	A tarefa não existe, o cursor de paginação é inválido ou a conta não pode visualizá-la.
404	`result_not_found`	`Result not found.`	O resultado não existe, ainda não está pronto, o ID não corresponde ou a conta não pode baixá-lo.
410	`artifact_expired`	`The result has expired.`	O resultado ultrapassou seu período de retenção.
413	`request_too_large`	`Request body is too large. Reduce the request size and try again.`	O corpo completo da requisição ultrapassa 32 MiB.
413	`image_too_large`	`Image is too large. Reduce the image size and try again.`	Uma imagem decodificada da interface de imagens ultrapassa o limite de processamento do modelo.
422	`image_not_generated`	`The expected image was not generated.`	O provedor de modelos concluiu a requisição, mas não retornou uma imagem utilizável.
429	`rate_limited`	`Too many requests. Please slow down and retry.`	A AIHubMix limitou a frequência da conta ou da API Key.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	O provedor de modelos de inferência retornou um erro de limite de frequência.
429	`too_many_downloads`	`Download limit exceeded for this result.`	O resultado atingiu o limite de downloads.
500	`internal_error`	`Internal error. Please retry.`	Ocorreu um erro interno que o cliente não pode corrigir.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Não foi possível conectar ao provedor de modelos ou ler completamente sua resposta.
502	`upstream_bad_response`	`Upstream service returned an invalid response.`	O provedor de modelos retornou uma resposta que a plataforma não conseguiu processar.
502	`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	O provedor de modelos retornou um erro de serviço.
503	`model_unavailable`	`The requested model is temporarily unavailable.`	O modelo selecionado está temporariamente indisponível.
503	`service_unavailable`	`Service is temporarily unavailable. Please retry.`	O serviço de consulta, download ou resultados está temporariamente indisponível.
504	`sync_timeout`	`Generation timed out. Please retry.`	A geração síncrona não terminou dentro do tempo de espera.

O message de media_form_unsupported é gerado a partir de uma causa confirmada:

Caso	`message`
Formato não suportado	`Unsupported <media-kind> format: <detected-format>. Supported formats for this model: <allowed-formats>.`
Dados de imagem ou vídeo inválidos	`The <media-kind> data is invalid. Provide a valid <media-kind>.`
Dados inválidos sem tipo de mídia determinado	`The media data is invalid. Provide valid media data.`
URL de mídia inacessível	`The <media-kind> URL could not be accessed. Make sure it is publicly accessible and returns a valid <media-kind>.`
Não foi possível decodificar a mídia	`Unable to process the <media-kind>. Check that the <media-kind> data or URL is valid and supported.`
Mídia grande demais em uma tarefa que não é de imagem	`The <media-kind> is too large. Reduce the <media-kind> size and try again.`
Não foi possível determinar uma causa segura	`Unable to process the media. Check that the media data or URL is valid and supported.`

Por exemplo, se um modelo aceita PNG, JPEG, WebP, HEIC e HEIF, uma imagem GIF retorna:

Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF.

HTTP 200 + Task com `status=failed`

Uma consulta bem-sucedida não significa que a geração foi concluída com sucesso. Quando a tarefa possui status=failed, o cliente obtém a causa em error.code e error.message:

{
  "id": "task_01K0ABCDEF",
  "status": "failed",
  "error": {
    "code": "media_form_unsupported",
    "message": "Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF."
  }
}

Task `code`	`message`	Descrição
`media_form_unsupported`	Mensagem dinâmica de mídia, conforme descrito acima.	Erro de formato, dados, URL, decodificação ou tamanho da mídia de uma tarefa assíncrona.
`image_too_large`	`Image is too large. Reduce the image size and try again.`	A imagem de entrada de uma tarefa assíncrona ultrapassa o limite.
`image_not_generated`	`The expected image was not generated.`	O provedor de modelos não retornou uma imagem utilizável.
`upstream_rejected`	`Upstream service rejected the request.`	O provedor de modelos rejeitou a criação da tarefa.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	O provedor de modelos limitou a frequência das requisições.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Não foi possível conectar ao provedor de modelos ao criar a tarefa ou ler completamente sua resposta.
`upstream_bad_response`	`Upstream service returned an invalid response.`	Não foi possível processar a resposta do provedor de modelos.
`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	O provedor de modelos não conseguiu criar ou executar a tarefa.
`upstream_empty_output`	`The upstream service completed without producing a usable result. Please retry.`	O provedor de modelos concluiu sem produzir um resultado utilizável.
`output_policy_violation`	`Generated content was rejected by the content policy.`	O conteúdo gerado foi rejeitado pela política de conteúdo.
`sync_timeout`	`Generation timed out. Please retry.`	O tempo de espera da geração foi excedido.
`internal_error`	`Internal error. Please retry.`	Ocorreu um erro interno ao processar a tarefa assíncrona.

Exemplo completo de vídeo

import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/videos",
    headers=headers,
    json={
        "model": "wan2.6-t2v",
        "prompt": "A cat playing jazz on a piano",
        "duration": 5,
        "size": "1280x720",
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] == "completed":
    result = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}/content",
        headers=headers,
        timeout=120,
    )
    result.raise_for_status()
    with open("result.mp4", "wb") as file:
        file.write(result.content)
else:
    raise RuntimeError(task.get("error") or task["status"])

import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "wan2.6-t2v",
    prompt: "A cat playing jazz on a piano",
    duration: 5,
    size: "1280x720",
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status === "completed") {
  const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, {
    headers,
  });
  if (!result.ok) throw new Error(await result.text());
  await writeFile("result.mp4", Buffer.from(await result.arrayBuffer()));
} else {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

Perguntas frequentes

As tarefas de mídia devem ser consultadas em /ai/v1/tasks/{id} ou na API de detalhes de mídia? Use a API de detalhes de mídia para acompanhar o status da geração: /ai/v1/images/{id} para imagens e /ai/v1/videos/{id} para vídeos. /ai/v1/tasks/{id} retorna um instantâneo somente leitura. Por que o campo seconds em uma requisição de vídeo causa erro de parâmetro? O protocolo padrão /ai/v1/videos usa o inteiro duration em segundos. Os valores permitidos dependem dos parâmetros aceitos pelo modelo correspondente. Por que resolution causa erro de parâmetro em alguns modelos de vídeo? O protocolo padrão de vídeo contém resolution e size, mas cada modelo pode restringir os campos. Por exemplo, wan2.6-t2v usa size e não aceita resolution. Como localizar uma tarefa de mídia depois de perder a resposta de criação? Solicite GET /ai/v1/images para imagens ou GET /ai/v1/videos para vídeos. As listas aceitam os parâmetros de paginação after, limit e order. Por que os campos de output são diferentes entre as duas APIs de detalhes? A API de detalhes de mídia fornece os campos simplificados necessários para download direto. A API de tarefas unificadas também fornece result_id e content_type, além de truncated para respostas LLM arquivadas. O que fazer se o Webhook não for recebido? Verifique se o endereço de callback pode ser acessado publicamente e retorna 2xx rapidamente. Em seguida, consulte o status final pela API de detalhes de mídia.

Última atualização: 2026-08-12

Tutorial em vídeo: tarefas assíncronas

Ativar tarefas assíncronas no console

​Início rápido

​Como escolher entre os três grupos de APIs

​Diferenças entre as APIs de mídia e de tarefas unificadas

​Como descobrir modelos de mídia assíncronos e obter seus esquemas

​Listar modelos compatíveis com as APIs assíncronas

​Obter o esquema de solicitação de um modelo

​Modelos e campos compatíveis

​Modelos para recuperação de interrupção de LLM

​Como criar uma tarefa de imagem

​Imagem síncrona

​Imagem assíncrona

​Campos padrão de imagem

​Como criar uma tarefa de vídeo

​Campos padrão de vídeo

​Objeto de tarefa de mídia

​Descrição dos status

​Como consultar tarefas de mídia

​Consultar detalhes da mídia

​Consultar a lista de mídia

​Como usar a API de tarefas unificadas

​Como baixar resultados de mídia

​Baixar imagens

​Baixar vídeo

​Como usar Webhook

​Requisição de callback

​Novas tentativas e desduplicação

​Como funciona a recuperação de interrupção de LLM

​Respostas e códigos de erro

Enviar feedback sobre erros HTTP 5xx

​Erros HTTP não 2xx

​HTTP 200 + Task com status=failed

​Exemplo completo de vídeo

​Perguntas frequentes

Início rápido

Como escolher entre os três grupos de APIs

Diferenças entre as APIs de mídia e de tarefas unificadas

Como descobrir modelos de mídia assíncronos e obter seus esquemas

Listar modelos compatíveis com as APIs assíncronas

Obter o esquema de solicitação de um modelo

Modelos e campos compatíveis

Modelos para recuperação de interrupção de LLM

Como criar uma tarefa de imagem

Imagem síncrona

Imagem assíncrona

Campos padrão de imagem

Como criar uma tarefa de vídeo

Campos padrão de vídeo

Objeto de tarefa de mídia

Descrição dos status

Como consultar tarefas de mídia

Consultar detalhes da mídia

Consultar a lista de mídia

Como usar a API de tarefas unificadas

Como baixar resultados de mídia

Baixar imagens

Baixar vídeo

Como usar Webhook

Requisição de callback

Novas tentativas e desduplicação

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

Respostas e códigos de erro

Erros HTTP não 2xx

HTTP 200 + Task com `status=failed`

Exemplo completo de vídeo

Perguntas frequentes