Vidu

Vidu Q3

vidu-q3-mix/reference-to-video

Modelo de geração de vídeo a partir de imagem de referência voltado para anúncios e vídeos curtos para redes sociais, capaz de restringir a aparência do sujeito e a composição, ideal para produzir rapidamente e iterar em várias versões

vidu-q3-ad/reference-to-video vidu-q3-mix/reference-to-video

Experimentar vidu-q3-mix/reference-to-video

Entrada

Saída

Preencha os parâmetros e gere — os resultados aparecerão aqui.

Preços

vidu-q3-mix/reference-to-video per second

Especificações	Preço unitário
1280*720	$0.1555
1280*960	$0.1555
1280*1280	$0.1555
960*1280	$0.1555
720*1280	$0.1555
1920*1080	$0.1865
1920*1440	$0.1865
1808*1808	$0.1865
1440*1920	$0.1865
1080*1920	$0.1865

Visão geral do posicionamento

Linha de geração de vídeo a partir de imagem de referência do Vidu Q3: utiliza de 1 a 7 imagens de referência (personagem, objeto ou estilo) para restringir o sujeito da cena e, junto com o prompt, gera vídeos curtos de 1 a 16 segundos, com saída em duas resoluções (720P e 1080P), cinco proporções de tela e opção de gerar áudio sincronizado com a imagem. Ideal para desenvolvedores que precisam manter a aparência de personagens ou produtos consistente em fragmentos de múltiplas tomadas e produzir rapidamente versões candidatas, para criação de materiais publicitários, vitrines de e-commerce e curtas de personagem.

Destaques principais

Referências múltiplas que restringem a consistência do sujeito — é possível enviar até 7 imagens de referência e citá-las no prompt na ordem Image1, Image2, restringindo respectivamente personagens, objetos e o estilo geral.
Áudio opcional gerado em sincronia com a imagem — ao ativar audio, gera-se som correspondente à imagem; ao desativar, o vídeo é mudo, permitindo decidir sob demanda se haverá dublagem posterior.
Duração e proporção de tela com controle fino — duração ajustável continuamente de 1 a 16 segundos, com proporções 16:9, 4:3, 1:1, 3:4 e 9:16, sem necessidade de recorte secundário para materiais verticais ou horizontais.
seed para reproduzir resultados — com a semente fixa, é possível repetir a geração para a mesma combinação de prompt e imagens de referência, facilitando a comparação de ajustes de parâmetros e a regressão de versões.

Descrição das capacidades

Geração de vídeo a partir de imagem de referência: gera com base em 1 a 7 imagens JPG, PNG ou WEBP como referência de aparência e composição, com máximo de 50MB por imagem e proporção de aspecto de 1:4 a 4:1, facilitando reutilizar configurações de personagens ou imagens de produtos existentes.

Vinculação entre prompt e índice de imagem: o prompt tem no máximo 5000 caracteres e pode descrever simultaneamente cena, movimento, câmera e som, especificando pela ordem do array, via Image1, Image2, a função de cada imagem de referência.

Saída em duas resoluções: os tamanhos de saída cobrem as faixas 720P e 1080P, cada uma com cinco proporções de tela, permitindo escolher diretamente a especificação final conforme o canal de veiculação.

Controle de áudio e duração: a chave audio determina se será gerado som correspondente; duration assume valores de 1 a 16 segundos, atendendo desde animações curtas até tomadas completas de curta-metragem.

Controle de marca d'água e semente: a marca d'água opcional de geração por IA vem desativada por padrão; combinada com o parâmetro seed, fixa a semente aleatória, facilitando reproduzir e rastrear um resultado durante testes em lote.

Cenários de aplicação

Equipes de e-commerce e produto: vídeos de demonstração a partir de várias imagens de produto — restringir a aparência com imagens do produto em múltiplos ângulos e produzir clipes de demonstração de alguns segundos para páginas de detalhe e materiais de veiculação.
Equipes de criação publicitária: storyboard guiado por imagens de configuração de personagem — gerar tomadas curtas em 9:16 ou 16:9 com imagens de referência de personagem e cena, como versões candidatas para propostas e testes A/B.
Criadores de curtas e anime: fragmentos com personagens consistentes — gerar tomadas em lote com imagens de referência fixas de personagem e montar fragmentos curtos orientados por personagem para prova de conceito.
Produção de conteúdo social que precisa de som — ativar a geração de áudio para curtas verticais com som, usados diretamente na avaliação de amostras antes da publicação em redes sociais.

Limitações e recomendações de escolha

O limite de duração por geração é de 16 segundos; vídeos longos ou narrativas contínuas complexas exigem storyboard próprio, múltiplas gerações e edição/montagem posterior. As imagens de referência devem ser arquivos JPG, PNG ou WEBP acessíveis publicamente; materiais com proporção de aspecto fora de 1:4 a 4:1 não podem ser usados. A chave de áudio vem desativada por padrão e deve ser explicitamente ativada quando o som for necessário. Se a necessidade for geração convencional de vídeo a partir de uma única imagem, consulte outras linhas da mesma família; para longas-metragens ou narrativas mais complexas, o posicionamento desta linha em fragmentos únicos não é adequado.

Criar uma tarefa de geração

POST https://api.hiapi.ai/v1/tasks

Cabeçalhos

AuthorizationstringObrigatório

Chave de API da conta. Obrigatória em toda requisição. Exemplo: Bearer YOUR_HIAPI_API_KEY. Obter chave de API

Content-TypestringOpcional

O corpo da requisição é sempre interpretado como JSON; se enviado, apenas application/json (charset opcional) é aceito — qualquer outro valor retorna 415. Exemplo: application/json.

Idempotency-KeystringOpcional

Chave de idempotência, até 255 bytes. Retries com a mesma chave da mesma conta criam a tarefa apenas uma vez; replays retornam o taskId original.

Chave de idempotência

Em timeouts de rede ou retries automáticos do cliente, a mesma chave cria a tarefa apenas uma vez, sem cobrança duplicada (escopo = a conta da chave de API). Use um identificador de negócio exclusivo (ex.: "order-42"); replays retornam o taskId original e as chaves expiram 24 h após a primeira requisição. A matriz completa de cenários está na introdução da API assíncrona unificada.

Corpo

modelstringObrigatório

Valor fixo atual: vidu-q3-mix/reference-to-video

routestringOpcional

Valor fixo atual: default

inputobjectObrigatório

Objeto de parâmetros de negócio para vidu-q3-mix/reference-to-video e a rota default — veja a tabela de parâmetros abaixo.

seedintegerOpcionalmin 0max 2147483647

Semente aleatória usada para reproduzir o resultado da geração, um número inteiro entre 0 e 2147483647.

sizestringOpcionalPadrão: "1280*720"

Dimensões da imagem de saída, no formato WIDTH*HEIGHT, padrão 1280*720; dividido em duas faixas, 720P e 1080P, cada uma com várias proporções de aspecto, e o preço cobrado por segundo varia conforme a faixa.

Opções:1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808

Mostrar tudo (2)

1440*19201080*1920

audiobooleanOpcionalPadrão: false

Define se deve ser gerado áudio correspondente à imagem, valor booleano, padrão false, ou seja, sai um vídeo sem som.

promptstringObrigatóriominLength 1maxLength 5000

Prompt que descreve a cena, o movimento, a câmera e o som; as imagens de referência são citadas no prompt por índices como Image1, Image2, na ordem do array.

durationintegerObrigatórioPadrão: 5min 1max 16

Duração do vídeo de saída, em segundos, um número inteiro entre 1 e 16, padrão 5.

watermarkbooleanOpcionalPadrão: false

Define se deve ser adicionada uma marca d'água de geração por IA no canto inferior direito da imagem, valor booleano, padrão false.

reference_image_urlsarrayObrigatóriominItems 1maxItems 7

Array de imagens de referência, forneça de 1 a 7 imagens de referência (pessoa, objeto ou estilo), cujos elementos são URLs de imagem nos formatos JPG/PNG/WEBP, com no máximo 50MB por imagem, proporção de aspecto entre 1:4 e 4:1 e acesso público.

Array [ string ]

callbackobjectOpcional

Configuração de notificação de estado terminal. Se omitida, sem callback: consulte a tarefa por conta própria.

Callbacks (Webhook)

Informe callback.url na criação e o HiAPI fará POST no seu serviço no estado terminal, sem polling. O corpo do callback replica a estrutura do detalhe da tarefa; assinatura, retries e idempotência estão descritos na introdução da API assíncrona unificada.

urlstringObrigatório

Obrigatória se callback estiver presente. No estado terminal é enviado um POST para esta URL; deve ser uma URL http(s) válida.

whenstringOpcionalPadrão: "final"

Atualmente só há suporte a final — notifica tanto em success quanto em fail.

Opções:final

storagestringOpcionalPadrão: "temp"

Nível de armazenamento de artefatos: temp (padrão, ~7 dias) ou persistent (longo prazo, cobrado por tamanho). Saldo insuficiente ou limite excedido ⇒ rebaixamento silencioso para temp; o nível efetivo aparece na resposta de detalhes.

Opções:temppersistent

Exemplos de requisição

# Envia uma tarefa assíncrona; retorna um taskId imediatamente (sem esperar a geração)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vidu-q3-mix/reference-to-video",
  "input": {
    "size": "1280*720",
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "watermark": false,
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "vidu-q3-mix/reference-to-video",
    input: {
      "size": "1280*720",
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "watermark": false,
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "vidu-q3-mix/reference-to-video",
        "input": {
          "size": "1280*720",
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "watermark": False,
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obter detalhes da tarefa

GET https://api.hiapi.ai/v1/tasks/:id

Campos da resposta

taskIdstringObrigatório

ID da tarefa, sempre com prefixo tk-hiapi-.

modelstringObrigatório

Nome completo resolvido do modelo. Tarefas enviadas com o parâmetro route retornam base@route (ex.: gpt-image-2/text-to-image@ext); caso contrário, igual ao nome enviado.

routestringOpcional

Presente apenas se o parâmetro route explícito foi usado; ecoa o valor enviado.

statusstringObrigatório

Estado da tarefa.

Valores de status

queued Na fila, ainda não iniciada. handling Em processamento. archiving Processamento concluído, preparando artefatos. success Terminal: concluído, artefatos disponíveis (retorna output). fail Terminal: falha (retorna error). Após o envio, acompanhe status: success e fail são terminais, os demais não. Faça polling a cada 1–3 s até o estado terminal. Em caso de sucesso, baixe os artefatos em output[].url e transfira antes de expireAt; para retenção longa, use storage: "persistent" na criação.

creatednumberObrigatório

Momento de criação da tarefa (segundos Unix).

completednumberObrigatório

Segundos Unix do estado terminal; 0 enquanto não terminal.

outputarrayOpcional

Presente apenas com status == success. Lista de artefatos — sempre um array; uma tarefa pode retornar vários types ao mesmo tempo (ex.: video + first_frame).

Array [ object ]

Itens do array

urlstringObrigatório

URL do artefato, baixável diretamente.

typestringObrigatório

Valores possíveis no momento: video, image, audio, first_frame, last_frame, thumbnail; poderão ser ampliados.

expireAtnumberObrigatório

Segundos Unix de disponibilidade do artefato; baixe ou transfira antes da expiração.

errorobjectOpcional

Presente apenas com status == fail.

codestringObrigatório

Código de erro de negócio.

messagestringObrigatório

Descrição do erro.

Exemplos de resposta

Sucesso

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Em processamento (não final)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Falhou

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}