Geração de vídeos

Início rápido

A geração de vídeo é sempre assíncrona. O exemplo usa wan2.6-t2v e um 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"
  }'

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

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

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

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 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 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.

Respostas e códigos de erro

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

Status HTTP	Código de erro	Descrição
400	`invalid_request`	Tipo ou valor de parâmetro incorreto
400	`result_id_required`	A tarefa unificada possui vários resultados, mas nenhum `result_id` foi informado no download
400	`webhook_invalid`	URL de Webhook inválida ou filtro sem URL
400	`webhook_events_filter_invalid`	Lista de eventos de Webhook inválida
401	`authentication_failed`	API Key ausente ou inválida
403	`async_not_enabled`	Tarefas assíncronas não ativadas para a conta
404	`task_not_found`	Tarefa ou cursor de paginação inexistente
404	`result_not_found`	Resultado inexistente ou indisponível para download no momento
410	`artifact_expired`	Resultado expirado
413	`request_too_large`	Corpo da requisição maior que 32 MiB
429	`too_many_downloads`	Limite de downloads do resultado excedido
503	`async_unavailable`	Serviço de imagens assíncronas temporariamente indisponível

error.tid é o ID de rastreamento da requisição. Informe-o ao suporte técnico durante a investigação.

Exemplo completo

Estes exemplos criam uma tarefa, consultam seu estado e baixam o resultado MP4.

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));
}

Começar

Recursos de gateway

Capacidades do modelo

Referência de protocolo

Gestão de plataforma

Privacidade e termos

Geração de vídeos

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 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 vídeo

Como usar Webhook

Requisição de callback

Novas tentativas e desduplicação

Respostas e códigos de erro

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 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 vídeo

​Como usar Webhook

​Requisição de callback

​Novas tentativas e desduplicação

​Respostas e códigos de erro

​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 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 vídeo

Como usar Webhook

Requisição de callback

Novas tentativas e desduplicação

Respostas e códigos de erro

Exemplo completo