Geração de imagens

Início rápido

O endpoint nativo de imagens é síncrono por padrão. Defina o booleano async como true para criar uma tarefa em segundo plano. O exemplo usa qwen-image-2.0.

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",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

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

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

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.

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

Objeto de tarefa de mídia

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

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "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/images/{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/images?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": "image",
      "model": "qwen-image-2.0",
      "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=image&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": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

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.

Como usar Webhook

Imagens assíncronas e vídeos aceitam Webhooks no nível da 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 tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "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": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

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.

Respostas e códigos de erro

Esta seção se aplica a /ai/v1/images/* e às tarefas de imagem. Para erros de vídeo, consulte a API de vídeo.

Falha na solicitação atual: um status HTTP diferente de 2xx indica falha na criação, consulta ou download atual. Consulte Falhas de solicitações HTTP.
Falha na execução da tarefa: a consulta retorna HTTP 200, mas a tarefa tem status=failed e o motivo consta no campo error. Consulte Falhas na execução de tarefas.
Falha na leitura do resultado de um item: a lista retorna HTTP 200, mas uma tarefa contém output_error. Consulte Falhas na leitura de resultados individuais.

A coluna message apresenta o texto em inglês retornado pela API, e a coluna de explicação descreve seu significado e como proceder. Os erros de validação mostram mensagens gerais; a resposta real pode especificar campos e restrições. Identifique o tipo de erro por code, sem depender de uma correspondência exata com o texto completo de message.

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

Relatar um erro HTTP 5xx

Se a solicitação retornar HTTP 5xx, envie um relato e inclua error.tid.

Falhas de solicitações HTTP

Os status HTTP abaixo se aplicam à falha da solicitação atual. Consulte a tabela de falhas na execução de tarefas para erros de tarefas já criadas.

Parâmetros da solicitação e mídia de entrada

HTTP	`code`	`message`	Explicação
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	O corpo da solicitação, os parâmetros de consulta ou os tipos dos parâmetros estão incorretos. Verifique formato, tipos e valores conforme a mensagem de erro.
404	`model_not_found`	`The requested model was not found. Check the model name.`	O modelo solicitado não existe. Verifique o nome do modelo.
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	Os parâmetros não atendem aos requisitos de entrada do modelo selecionado. Consulte o schema do modelo e corrija os campos indicados no erro.
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	O modelo não aceita essa combinação de operação e mídia de entrada. Altere a combinação ou escolha um modelo compatível.
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	Os parâmetros solicitados excedem as capacidades do modelo. Ajuste-os conforme o erro ou escolha outro modelo.
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	O modelo não aceita esse formato de mídia. Use um formato indicado na mensagem ou em `error.details.allowed_mime_types`. Se não houver lista, consulte os requisitos de entrada do modelo.
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	Os dados de mídia foram confirmados como inválidos, por exemplo, por base64 corrompido ou estrutura incorreta de data URI. Verifique a integridade e a codificação e forneça mídia válida.
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	Não foi possível acessar ou ler o link da mídia. Verifique se o link é válido, acessível publicamente e retorna conteúdo de mídia válido.
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	A mídia de entrada não pôde ser processada e uma causa mais específica não foi confirmada. Verifique se os dados ou a URL são válidos e se o modelo aceita o formato.
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	A mídia da tarefa de imagem excede o limite atual de processamento. Reduza o tamanho conforme `error.details.max_bytes` ou o limite da mensagem e tente novamente.
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	O corpo HTTP completo excede 32 MiB. Reduza o corpo enviado, incluindo texto, parâmetros e mídia codificada incorporada.

Limites de tamanho

Tamanho da mídia: tarefas de imagem acima do limite retornam image_too_large. Consulte o limite na mensagem ou em error.details.max_bytes.
Tamanho total da solicitação: request_too_large indica que o corpo HTTP excede 32 MiB, incluindo texto, parâmetros e mídia codificada incorporada. Ao enviar apenas uma URL, o link conta no corpo; o arquivo de destino ainda precisa respeitar os limites de mídia do modelo.
Tamanho real: error.details.actual_bytes só é fornecido quando o tamanho completo é conhecido. O campo pode ser omitido se a leitura por URL for interrompida ao atingir o limite de leitura.

Formatos aceitos Dependem do modelo selecionado. Consulte primeiro error.details.allowed_mime_types ou a lista de formatos da mensagem. Se não houver lista, consulte o Schema do modelo. Marcadores nas mensagens

{media_kind}: tipo real de mídia. Quando confirmado, as mensagens de invalid_media_data e media_url_unreachable também usam image ou video.
{max_bytes}: limite em bytes. Se o limite da imagem for desconhecido, a mensagem será The image is too large. Reduce the image size and try again.
{allowed_formats}: lista de formatos permitidos. Erros de formato podem acrescentar Use one of: {allowed_formats}.

Solicitações de geração e resultados retornados

HTTP	`code`	`message`	Explicação
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	O provedor de modelos concluiu a solicitação sem retornar uma imagem utilizável. Ajuste a solicitação ou escolha outro modelo e tente novamente. Se o problema persistir, contate o suporte com o ID da solicitação. Não repita a geração automaticamente apenas por receber HTTP 502.
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	O provedor de modelos bloqueou o conteúdo gerado e não retornou uma imagem utilizável. Altere o prompt ou o conteúdo de entrada e tente novamente. Esta geração não é cobrada.
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	O provedor de modelos rejeitou a solicitação. Esse código, isoladamente, não confirma uma violação de conteúdo. Verifique e altere os parâmetros e a entrada antes de tentar novamente.
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	O provedor de modelos retornou uma resposta que a plataforma não consegue processar. Isso não confirma a ausência de resultados gerados. Contate o suporte com o ID da solicitação; não interprete o erro como parâmetro inválido ou resultado vazio.
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao retornou um código específico de rejeição por privacidade de imagens de pessoas reais. Conclua a verificação de pessoas reais e use um recurso `asset://` ativado. Consulte a documentação de recursos de pessoas reais.
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	A geração não terminou no período de espera. O tempo esgotado não comprova que a solicitação não foi executada. Contate o suporte com o ID da solicitação; não consulte um ID de tarefa que não tenha sido retornado a você.
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	A tarefa foi enviada ao provedor de modelos, mas seu estado posterior não pôde ser confirmado. Não a envie novamente. Contate o suporte com o ID da solicitação e, se disponível, o ID da tarefa.

Conta e permissões

HTTP	`code`	`message`	Explicação
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	A API Key está ausente ou é inválida. Verifique o cabeçalho `Authorization` e a API Key.
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	A conta não tem cota suficiente. Adicione créditos e tente novamente.
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	A conta ou a API Key não tem acesso. Verifique as permissões da conta, da API Key e as restrições de IP.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	As tarefas assíncronas não estão ativadas na conta. Ative-as pelo link do console na resposta e tente novamente.

Disponibilidade do serviço e limites de requisições

HTTP	`code`	`message`	Explicação
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	A frequência de solicitações está muito alta. Reduza-a e tente novamente.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	O provedor de modelos está limitando as solicitações. Tente mais tarde e evite reenvios imediatos e repetidos.
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	Ocorreu um erro interno na plataforma. Contate o suporte com o ID da solicitação; não é necessário alterar repetidamente uma entrada válida.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	O provedor de modelos está temporariamente indisponível, possivelmente por falha de conexão, erro no serviço do provedor ou falha na leitura da resposta. O código não confirma se resultados foram gerados. Se o problema persistir, contate o suporte com o ID da solicitação.
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	O provedor de modelos está indisponível. A tabela mostra a mensagem padrão; a resposta real pode trazer orientações mais específicas. Identifique o tipo de erro por `code` e contate o suporte com o ID da solicitação.
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	O modelo está temporariamente indisponível. Tente mais tarde ou escolha outro modelo. Se o problema persistir, contate o suporte com o ID da solicitação.
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	O serviço está temporariamente indisponível. Tente a operação novamente mais tarde. Se um download falhou, tente baixá-lo novamente sem repetir a geração.

provider_unavailable indica uma falha confirmada do provedor de modelos. Um status genérico 429 ou 4xx, isoladamente, não confirma problemas de cota, moderação de conteúdo ou parâmetros.

Consulta de tarefas e download de resultados

HTTP	`code`	`message`	Explicação
404	`task_not_found`	`The task was not found.`	A tarefa não existe ou não pertence à conta atual. Verifique o ID da tarefa e confirme que a API Key pertence à conta que a criou.
404	`result_not_found`	`The result was not found.`	O resultado não existe ou você não tem permissão para lê-lo. Verifique o ID da tarefa, o ID do resultado e a API Key. Um ID de resultado reconhecidamente inválido não passa a retornar 409 porque a tarefa continua em execução.
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	O cursor de paginação é inválido ou expirou. Remova `after`, consulte a primeira página e use o novo cursor retornado nessa lista.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	A tarefa tem vários resultados, mas `result_id` não foi informado. Escolha um resultado na saída da tarefa e informe seu `result_id`.
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	A tarefa está na fila ou em execução, e o resultado ainda não está pronto. Continue consultando o estado e faça o download quando estiver disponível. Não é necessário gerar novamente.
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	O resultado excedeu o período de retenção e não pode mais ser baixado. Envie uma nova solicitação de geração se necessário.
429	`too_many_downloads`	`Download limit exceeded for this result.`	O limite de downloads foi atingido. Verifique os resultados já salvos. Apenas esperar não garante a restauração do número de downloads.

Falhas na execução de tarefas

Após a criação de uma tarefa, falhas de geração são indicadas por status=failed e pelo campo error da tarefa. Uma consulta bem-sucedida continua retornando HTTP 200.

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

Task `code`	`message`	Explicação
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	O provedor de modelos concluiu a solicitação sem retornar uma imagem utilizável. Ajuste a solicitação ou escolha outro modelo e envie uma nova tarefa. Não repita a geração automaticamente sem avaliar o erro.
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	O provedor de modelos bloqueou o conteúdo gerado e não retornou uma imagem utilizável. Altere o prompt ou a entrada e envie uma nova tarefa. Esta geração não é cobrada.
`output_policy_violation`	`Generated content was rejected by the content policy.`	O conteúdo gerado não passou pela moderação. Altere o prompt ou a entrada e envie uma nova tarefa. Aplicam-se as regras de cobrança existentes para moderação de conteúdo; consulte os registros de faturamento para cobranças anteriores.
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	O provedor de modelos rejeitou a solicitação. Esse código, isoladamente, não confirma uma violação de conteúdo. Verifique e altere os parâmetros e a entrada antes de enviar uma nova tarefa.
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	A plataforma não consegue processar a resposta do provedor de modelos. Isso não confirma a ausência de resultados gerados. Contate o suporte com o ID da tarefa.
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	A tarefa foi enviada ao provedor de modelos, mas seu estado posterior não pôde ser confirmado. Não a envie novamente. Contate o suporte com o ID da tarefa.
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	Existe um resultado gerado, mas a plataforma não conseguiu salvá-lo ou entregá-lo. Não repita a geração automaticamente. Contate o suporte com o ID da tarefa para investigar primeiro o resultado existente.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	O provedor de modelos está limitando as solicitações. Tente mais tarde e evite reenvios imediatos e repetidos.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Durante a execução ocorreu falha de conexão com o provedor de modelos, erro no serviço do provedor ou falha na leitura da resposta. O código não confirma se resultados foram gerados. Se o problema persistir, contate o suporte com o ID da tarefa.
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	O provedor de modelos está indisponível. A tabela mostra a mensagem padrão; a resposta real pode trazer orientações mais específicas. Identifique o tipo de erro por `code` e contate o suporte com o ID da tarefa.
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao retornou um código específico de rejeição por privacidade de imagens de pessoas reais. Conclua a verificação de pessoas reais e use um recurso `asset://` ativado. Consulte a documentação de recursos de pessoas reais.
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	A tarefa de geração excedeu o tempo de espera. Contate o suporte com o ID da tarefa.
`internal_error`	`An internal error occurred. Contact support with the task ID.`	Ocorreu um erro interno na plataforma. Contate o suporte com o ID da tarefa; não é necessário alterar repetidamente uma entrada válida.

Erros de mídia de entrada também podem aparecer em uma Task com falha e têm o mesmo significado da tabela acima. A consulta bem-sucedida continua retornando HTTP 200. O message dos erros de tamanho termina com submit a new task., orientando a reduzir a mídia e enviar uma nova tarefa. output_blocked indica um bloqueio confirmado sem imagem utilizável; esta geração não é cobrada. Para output_policy_violation, aplicam-se as regras de cobrança existentes para moderação. Consulte os registros de faturamento para cobranças anteriores.

Falhas na leitura de resultados individuais

Alguns itens das listas de tarefas de imagem e vídeo podem incluir output_error:

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

Esse campo indica que o resultado do item não pôde ser lido nesta consulta. A lista continua retornando HTTP 200 e o item contém output=[]. Seus campos id, status, error e a paginação são preservados; outras tarefas legíveis não são afetadas. Mesmo com status=completed, verifique output_error antes de considerar o resultado acessível. Contate o suporte com output_error.tid. Se o campo não incluir tid, forneça o ID da solicitação nos cabeçalhos da resposta atual. Esse erro não altera o estado da tarefa nem as cobranças e não aciona um Webhook. As listas de imagens e vídeos preservam o expires_at obtido. Itens com falha de leitura na lista unificada /ai/v1/tasks podem retornar expires_at=null; os resultados continuam sujeitos ao período de retenção original. Esse tratamento se aplica somente quando não é possível ler o resultado de um item e não há alternativa disponível. Falhas na consulta do lote inteiro pela API unificada de tarefas continuam retornando um erro HTTP; a mesma falha na consulta de detalhes continua retornando HTTP 500. Documentação relacionada: API de imagens · API de vídeo · Tarefas assíncronas

Exemplo completo

Estes exemplos criam uma tarefa assíncrona, consultam seu estado e salvam todas as imagens retornadas.

import base64
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/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    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/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

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/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
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/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

Começar

Recursos de gateway

Capacidades do modelo

Referência de protocolo

Gestão de plataforma

Geração de imagens

Início rápido

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

Como criar uma tarefa de imagem

Imagem síncrona

Imagem assíncrona

Campos padrão de imagem

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

Como usar Webhook

Requisição de callback

Novas tentativas e desduplicação

Respostas e códigos de erro

Relatar um erro HTTP 5xx

Falhas de solicitações HTTP

Parâmetros da solicitação e mídia de entrada

Solicitações de geração e resultados retornados

Conta e permissões

Disponibilidade do serviço e limites de requisições

Consulta de tarefas e download de resultados

Falhas na execução de tarefas

Falhas na leitura de resultados individuais

Exemplo completo

​Início rápido

​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

​Como criar uma tarefa de imagem

​Imagem síncrona

​Imagem assíncrona

​Campos padrão de imagem

​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

​Como usar Webhook

​Requisição de callback

​Novas tentativas e desduplicação

​Respostas e códigos de erro

Relatar um erro HTTP 5xx

​Falhas de solicitações HTTP

​Parâmetros da solicitação e mídia de entrada

​Solicitações de geração e resultados retornados

​Conta e permissões

​Disponibilidade do serviço e limites de requisições

​Consulta de tarefas e download de resultados

​Falhas na execução de tarefas

​Falhas na leitura de resultados individuais

​Exemplo completo

Início rápido

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

Como criar uma tarefa de imagem

Imagem síncrona

Imagem assíncrona

Campos padrão de imagem

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

Como usar Webhook

Requisição de callback

Novas tentativas e desduplicação

Respostas e códigos de erro

Falhas de solicitações HTTP

Parâmetros da solicitação e mídia de entrada

Solicitações de geração e resultados retornados

Conta e permissões

Disponibilidade do serviço e limites de requisições

Consulta de tarefas e download de resultados

Falhas na execução de tarefas

Falhas na leitura de resultados individuais

Exemplo completo