Vidu

Vidu Q4 Preview

vidu-q4-preview/reference-to-video

Primeira versão de pré-visualização pública da série Vidu Q4, focada em atuação de personagens e áudio nativo, com suporte a até 15 imagens e 3 trechos de áudio como referência de orientação, gerando vídeos de até 4K

vidu-q4-preview/image-to-video vidu-q4-preview/reference-to-video

Experimentar vidu-q4-preview/reference-to-video

Entrada

Criações

Ver todas as criações

Saída

video

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

Vidu Q4 Preview 参考生视频：Consistência de personagem e demonstração de áudio nativo

Estilo Consistência de Personagem · Áudio Nativo · Cenário de diálogo

Entradas de referência

reference_audio_urls
reference_image_urls
reference_image_urls

Prompt

A imagem de referência 1 define a protagonista: uma jovem vestindo um jaqueta de campo verde-oliva desgastada, com cabelo curto escuro e uma pequena cicatriz acima da sobrancelha esquerda. A imagem de referência 2 define seu antagonista: um homem alto de sobretudo cinza-carvão, cabeça raspada, com os ombros molhados pela chuva. O áudio de referência 1 fornece a voz da protagonista.

Cena: ao crepúsculo, uma passagem subterrânea de concreto molhada pela chuva, lâmpadas de sódio piscando de forma instável, poças rasas refletindo uma luz laranja quente. A abertura é um plano médio, com leve ângulo baixo; a mulher da imagem de referência 1 sai das sombras, respirando com dificuldade, o olhar fixo fora do quadro. Com a voz do áudio de referência 1, ela diz em tom baixo e contido: “Você não deveria ter voltado.” O homem da imagem de referência 2 vira lentamente a cabeça, o sobretudo balançando, e responde sem elevar o volume da voz. A câmera avança lentamente até um close-up do rosto dela, que sustenta o olhar dele, o maxilar tenso, e pisca uma vez; a chuva passa em frente à lente, e pequenas partículas flutuam na luz. A câmera permanece na mão, mas estável, sem cortes, um movimento contínuo, desfoque de movimento natural, textura cinematográfica de 35mm com granulação fina de filme.

Áudio: diálogo sincronizado, som ambiente de chuva, zumbido distante do tráfego, passos sobre concreto molhado e um leve som metálico no momento da transição de plano.

Copie o prompt completo e adapte-o para a sua própria geração.

Etiquetas

Preços

vidu-q4-preview/reference-to-video per second

Especificações	Preço unitário
540P	$0.0515
720P	$0.109
1080P	$0.1375
2K	$0.2175
4K	$0.446

Posicionamento e visão geral

A linha de geração de vídeo por referência do Vidu Q4 Preview é voltada para desenvolvedores que precisam manter personagens, cenários e voz consistentes no vídeo final. Basta enviar de 1 a 15 imagens de referência (personagens, cenários e objetos são todos válidos) e até 3 referências de áudio, junto com um prompt de texto, para gerar vídeos de 3 a 16 segundos, com resolução selecionável de 540p a 4K e áudio nativo sincronizado com a imagem por padrão. É ideal para produção de conteúdo curto em série, trechos de diálogo entre personagens e pré-visualização de cenas que exige comparação de múltiplas propostas.

Destaques principais

Múltiplas imagens de referência mantêm a consistência de personagens e cenários — é possível usar até 15 imagens de referência por geração para restringir personagens, cenários e objetos, referenciando-as em ordem no prompt, o que reduz a variação de aparência entre tomadas.
Geração de dublagem orientada por referência de áudio — é possível anexar até 3 amostras de voz MP3 de 3 a 12 segundos como referência de timbre, tornando o diálogo gerado mais próximo da voz especificada.
Áudio nativo incluído por padrão — por padrão, diálogos e efeitos sonoros são gerados em sincronia com o vídeo; também é possível desativar para obter material sem áudio, eliminando o retrabalho de separar faixas.
Duração, proporção e resolução ajustáveis — duração de 3 a 16 segundos, cinco proporções de tela e cinco níveis de resolução de 540p a 4K; a mesma linha atende necessidades de tela horizontal, vertical e diferentes níveis de nitidez.

Descrição das capacidades

Geração restringida por imagens de referência: insira de 1 a 15 imagens JPG, PNG ou WEBP e referencie-as em ordem no prompt para fixar a aparência dos personagens, o cenário e objetos-chave; ideal para vários vídeos que precisam manter a mesma imagem.

Dublagem com referência de timbre: anexe até 3 referências de voz MP3 de 3 a 12 segundos e especifique no prompt quem fala, para que o diálogo dos personagens tenha as características de timbre desejadas.

Chave de áudio sincronizado: o parâmetro audio fica ativado por padrão, gerando o vídeo final com diálogos e efeitos sonoros; ao desativar, obtém-se um vídeo apenas com imagem, facilitando a dublagem e trilha sonora na pós-produção.

Especificações de saída personalizáveis: suporta cinco proporções de tela — 16:9, 9:16, 1:1, 4:3 e 3:4 — e resoluções de 540p a 4K, produzindo diretamente vídeos adequados a diferentes canais de veiculação.

Descrição com prompts longos: o prompt pode ter até 20000 caracteres, comportando descrições estruturadas como divisão de papéis entre vários personagens, movimentação de câmera e falas de diálogo.

Cenários de aplicação

Criadores de conteúdo curto em série — usar o mesmo conjunto de imagens de referência de personagens e cenários para gerar vários curtas em lote, mantendo a aparência dos personagens uniforme, prontos para atualizações em redes sociais ou trechos de séries.
Produção de trechos de enredo com falas — fornecer imagens de referência dos personagens e amostras de timbre, além de escrever as falas, para produzir curtas com diálogos sincronizados, usados como pré-visualização de storyboard ou material final.
Comparação de múltiplas propostas para anúncios e vídeos de marca — trocar imagens de referência e prompts para testar rapidamente versões com diferentes enquadramentos e formas de abertura, permitindo que a equipe selecione a direção antes da filmagem oficial.
Adaptação de material para veiculação multiplataforma — gerar uma versão com cada proporção de tela e resolução para atender às necessidades de material em tela horizontal, vertical e entrega em alta definição.

Limitações e recomendações de escolha

O limite de duração por geração é de 16 segundos; narrativas mais longas exigem geração em segmentos e posterior montagem. O material de referência tem limite de quantidade: no máximo 15 imagens e 3 áudios, sendo que as referências de áudio só aceitam MP3 e cada trecho deve ter de 3 a 12 segundos. Por ser uma versão de pré-visualização, capacidades e parâmetros podem ser ajustados futuramente, não sendo recomendada para fluxos de produção em massa que exigem altíssima estabilidade de saída. Se for necessário apenas gerar a imagem a partir de um único quadro inicial, pode-se optar pela linha de geração por quadro inicial da mesma série; para tomadas contínuas mais longas, deve-se avaliar o custo de pós-produção da montagem em segmentos.

Perguntas frequentes

Ver todas as perguntas →

No image-to-video, posso definir a proporção da imagem por conta própria?

Não. A proporção do vídeo final segue totalmente a imagem do primeiro quadro: se enviar uma imagem horizontal, o resultado é horizontal; se enviar uma imagem vertical, o resultado é vertical. Portanto, se quiser 9:16 vertical, prepare um primeiro quadro em formato vertical. A proporção entre largura e altura do primeiro quadro deve estar entre 1:4 e 4:1; imagens excessivamente alongadas serão rejeitadas no momento do envio.
Para que serve o botão de áudio?

O áudio nativo vem ativado por padrão e gera diálogos, sons ambientes e efeitos sonoros sincronizados com a imagem; ao desativá-lo, a saída é um vídeo sem som, apenas com a imagem, adequado para fundos em loop, para você mesmo adicionar trilha sonora na pós-produção ou para inserir legendas. O botão não afeta o preço.
Qual é a relação entre a duração e o preço?

A cobrança é feita multiplicando a duração em segundos inteiros enviada pelo preço unitário por segundo da resolução escolhida; a ativação do áudio e a quantidade de imagens não participam do cálculo. Quanto maior a resolução, maior o preço unitário por segundo; a faixa 4K custa cerca de 8,7 vezes a faixa 540p. Os valores exatos estão na página de preços.
Para que cenários são adequadas as cinco resoluções?

540p serve para testar prompts e enquadramentos, e também é suficiente para fundos em loop de pequeno porte; 720p cobre a maioria das redes sociais e páginas web; 1080p é usado para veiculação convencional; 2K é adequado para telas grandes e exibição em TV; 4K é usado para exposições, imagens de nível cinematográfico ou tomadas que exigem recorte posterior e recomposição. Antes da versão final, teste com a resolução mais baixa; depois de definida, faça a saída na mais alta.

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-q4-preview/reference-to-video

routestringOpcional

Valor fixo atual: default

inputobjectObrigatório

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

audiobooleanOpcionalPadrão: true

Se deve gerar áudio nativo sincronizado com o vídeo (diálogos e efeitos sonoros); valor booleano, padrão true, quando definido como false produz um vídeo sem som.

promptstringObrigatóriominLength 1maxLength 20000

Prompt do conteúdo do vídeo, podendo referenciar materiais de referência por número de ordem (por exemplo, "o homem da imagem de referência 2 fala usando o áudio de referência 1"); string, com no máximo 20000 caracteres.

durationintegerOpcionalPadrão: 5min 3max 16

Duração do vídeo (em segundos); inteiro entre 3 e 16, padrão 5.

resolutionstringOpcionalPadrão: "720p"

Resolução do vídeo de saída; string, padrão 720p.

Opções:540p720p1080p2k4k

aspect_ratiostringOpcionalPadrão: "16:9"

Proporção da tela do vídeo de saída; string, padrão 16:9.

Opções:16:99:161:14:33:4

reference_audio_urlsarrayOpcionalmaxItems 3

Array opcional de URLs de áudios de referência, no máximo 3 trechos, usados como referência de timbre de voz; cada trecho suporta apenas MP3, com no máximo 50MB e duração de 3 a 12 segundos.

Array [ string ]

reference_image_urlsarrayObrigatóriominItems 1maxItems 15

Array de URLs de imagens de referência, contendo de 1 a 15 imagens usadas para manter a consistência de personagens, cenários e objetos; cada imagem suporta JPG, JPEG, PNG ou WEBP, com no máximo 50MB, pelo menos 128×128 pixels e proporção entre 1:4 e 4:1.

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-q4-preview/reference-to-video",
  "input": {
    "audio": true,
    "prompt": "…",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "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-q4-preview/reference-to-video",
    input: {
      "audio": true,
      "prompt": "…",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "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-q4-preview/reference-to-video",
        "input": {
          "audio": True,
          "prompt": "…",
          "duration": 5,
          "resolution": "720p",
          "aspect_ratio": "16:9",
          "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"
    }
  }
}