Blogue

Guia de uso

Guia de introdução ao Vidu Q3 Mix Reference-to-Video: limites de capacidade, parâmetros de API e pontos de cobrança

Perspectiva de decisão de integração e prática para desenvolvedores

Nov 13, 2026
Imagem de capa em baixo-relevo com camadas de papel desalinhadas e recuadas, fundo bege, bordas de papel em grafite e uma única folha em tom terracota, exibindo um ritmo calmo de estratificação.
Nesta página

Que problema este modelo resolve

A forma de entrada de um modelo de geração de vídeo determina se você consegue manter o "controle" nas mãos. O text-to-video recebe apenas um prompt, e a direção da imagem fica a cargo do modelo; o image-to-video recebe um primeiro quadro, e o modelo se encarrega de "colocá-lo em movimento". Já o reference-to-video (vídeo a partir de referência) segue um terceiro caminho: você fornece material de referência, e o modelo o consulta continuamente durante a geração, em vez de tratá-lo apenas como primeiro quadro.

O posicionamento do vidu-q3-mix/reference-to-video está nesse ramo. Ele atende a necessidades como:

  • Personagem ou sujeito precisa se manter consistente entre tomadas: você não tem material de vídeo pronto, mas tem uma ou mais imagens de referência que representam a aparência do sujeito e espera que, no vídeo final, o sujeito "pareça ainda ser ele".
  • Estilo e tom precisam ser ancorados: o material de referência carrega luz, material e tendência de composição, e o vídeo final segue essa linguagem visual, o que é mais controlável do que depender apenas de descrição textual.
  • Criar conteúdo dinâmico a partir de ativos estáticos: produtos de e-commerce, personagens de IP, esboços de design conceitual e outros ativos de imagem já existentes precisam ser convertidos em vídeos curtos.

Em outras palavras, se o seu desejo é "me dê um vídeo qualquer que corresponda à descrição", o text-to-video é mais direto; se o seu desejo é "este vídeo precisa se parecer com o que eu forneci", o reference-to-video é a ferramenta adequada. Ao escolher, pergunte-se primeiro: tenho um ponto de ancoragem visual que precisa ser preservado? Se sim, use-o.

No HiAPI.ai, este modelo compartilha o mesmo contexto de chamada dos outros modelos de vídeo; você não precisa montar uma lógica de integração separada para ele, e ao trocar de modelo o que muda principalmente são os parâmetros de capacidade, não a estrutura de engenharia.

Diferença crucial em relação ao image-to-video

A imagem de entrada do image-to-video é o "ponto de partida"; a entrada do reference-to-video é a "restrição". O primeiro dá ao modelo um quadro que ele deve continuar; o segundo dá ao modelo um conjunto de características que ele deve respeitar. Entender isso torna naturais todos os julgamentos posteriores sobre preparação de material e ajuste de parâmetros.

Três formas de entrada convergem para o mesmo destino: texto, imagem e material de referência finalmente desembocam na mesma saída de geração de vídeo.

Limites de capacidade e cenários não aplicáveis

Delimitar claramente o círculo de capacidade do modelo é mais importante do que memorizar o que ele suporta. Com base na definição de capacidade do reference-to-video, é possível explicitar os seguintes limites:

O que ele cobre

  • Gerar vídeo com base visual no material de referência: as características da imagem de referência são introduzidas no processo de geração.
  • Consistência do sujeito e continuidade de estilo: manter uma expressão visual relativamente estável em múltiplas gerações.
  • Controlar a direção do conteúdo com o prompt: o material de referência cuida do "parecer ou não", e o prompt cuida do "o que fazer".

O que ele não cobre

  • Não é substituto do text-to-video: sem material de referência, não se deve escrever um prompt extremamente longo para "simular" a imagem de referência; isso é usar a ferramenta errada, e tanto o efeito quanto o custo não compensam.
  • Não é uma ferramenta de replicação rigorosa quadro a quadro: reference-to-video não equivale a animar com precisão a imagem de referência, nem se deve esperar que ele se responsabilize por cada pixel da imagem de referência. Se a sua necessidade é "esta imagem precisa se mover exatamente como está", o image-to-video é mais adequado.
  • Não promete duração ilimitada: o limite de duração de uma única geração está sujeito aos parâmetros disponíveis na interface e no painel da plataforma; não projete o fluxo do produto com a ideia de "gerar o tempo que eu quiser".
  • Não substitui a pós-produção: legendas, edição, junção de múltiplos trechos e mixagem de faixas de áudio continuam sendo responsabilidade do seu pipeline.

O uso incorreto mais comum na escolha

O uso incorreto mais típico é tratar o reference-to-video como um "image-to-video mais barato". As semânticas de entrada dos dois são diferentes, e as expectativas de resultado também: quando você realmente precisa de alinhamento rigoroso do primeiro quadro, usar reference-to-video costuma produzir resultados "semelhantes em espírito, mas diferentes", e repetir tentativas só amplia o custo. Por outro lado, quando você precisa de estabilidade do sujeito entre múltiplas tomadas, alimentar imagens trecho a trecho com image-to-video tende a causar mais deriva de aparência.

A regra de decisão pode ser simplificada em uma frase: quer um ponto de partida, escolha image-to-video; quer uma restrição, escolha reference-to-video.

A plataforma central é o círculo de capacidade que o modelo cobre; as lacunas rebaixadas ao redor são as áreas fora dos limites de duração, dependência de entrada e consistência.

Parâmetros de API e pontos do fluxo de chamada

A complexidade de engenharia ao integrar esse tipo de modelo não está principalmente em "enviar a requisição", mas em "preparar a entrada" e "organizar o fluxo". A cadeia completa pode ser dividida em quatro etapas:

1. Preparação do material de referência

Antes de iniciar a chamada, normalize o material de referência: unifique dimensões e proporções, remova marcas d'água e elementos de fundo redundantes, e garanta que o sujeito esteja nítido e a iluminação consistente. Só com esta etapa bem feita o ajuste fino posterior de parâmetros faz sentido.

2. Construção da requisição

Uma chamada típica precisa organizar três tipos de informação na requisição:

  • Identificador de capacidade: especifique vidu-q3-mix/reference-to-video para direcionar a requisição ao ramo de capacidade correto.
  • Material de referência: localização ou handle de upload da imagem de referência; os nomes de campo específicos e formatos aceitos seguem a documentação da interface.
  • Descrição de geração: o prompt, descrevendo ação, movimento de câmera, ritmo e atmosfera, em vez de repetir a aparência já presente na imagem de referência.

Os nomes de campo específicos, campos obrigatórios e intervalos de valores devem seguir a documentação da interface e a página de detalhes do modelo no HiAPI.ai. Este artigo não inventa campos; basta montar a integração conforme a documentação.

3. Tarefa de geração

A geração de vídeo é essencialmente assíncrona: após o envio da requisição, retorna-se um identificador de tarefa, e o modelo leva um tempo para concluir a inferência. Seu servidor deve desacoplar "envio" e "obtenção do resultado", usando o identificador da tarefa para polling ou recebimento de callback, em vez de esperar dentro de uma requisição síncrona.

4. Obtenção do resultado e nova tentativa

Após obter o resultado, faça primeiro uma validação de disponibilidade (se o arquivo decodifica normalmente, se a duração corresponde ao esperado) e só então decida se deve tentar novamente. O ramo de nova tentativa deve ter limite máximo e registrar o motivo de cada falha — isso é crucial para estimar custos.

Como escrever o prompt

No prompt do reference-to-video, o foco deve estar nas "informações além da imagem de referência": o que o sujeito deve fazer no quadro, como a câmera se move, como o ambiente muda. Gastar espaço repetindo o que já está na imagem de referência é um desperdício comum. Quanto mais específica e próxima de instruções executáveis de imagem for a descrição, mais estável será o resultado da geração.

O fluxo de quatro camadas de papel corresponde à cadeia de chamada: primeiro prepare o material de referência, depois organize a requisição, dispare a tarefa de geração e, por fim, recupere o resultado; os ramos de retrocesso indicam o caminho de nova tentativa.

Estimar custos com $0.1865/segundo

A métrica de cobrança deste modelo é por segundo de vídeo de saída, com preço unitário de $0.1865 por segundo. Entendido isso, a estimativa de custo se torna uma simples multiplicação.

Fórmula de custo por vídeo

custo por vídeo = duração de saída (segundos) × $0.1865

Um vídeo final de 5 segundos custa 5 × 0.1865; 10 segundos custam 10 × 0.1865. Ao dobrar a duração, o custo dobra linearmente — não há faixas nem descontos ocultos de "gerar de uma vez sai mais em conta", então o orçamento de duração precisa entrar no design do produto desde o início.

Incluir as novas tentativas no cálculo

O custo real nunca é "o preço de um vídeo". A geração tem incerteza, e você precisa reservar orçamento de nova tentativa para falhas e resultados insatisfatórios:

custo total esperado = custo por vídeo × número esperado de tentativas
número esperado de tentativas ≈ 1 + taxa de nova tentativa

Por exemplo, se uma tarefa de geração de 8 segundos precisa em média de uma nova tentativa para obter um resultado utilizável, o custo real é 8 × 0.1865 × 2, e não 8 × 0.1865. Equipes com alta taxa de nova tentativa têm o custo multiplicado — este é um custo oculto que muitos integradores só descobrem depois de escalar.

Três alavancas de controle de orçamento

  • Primeiro curto, depois longo: na fase de depuração, use a duração mais curta para validar se o prompt e o material estão alinhados; só depois de confirmar a eficácia alongue. O custo de erro de vídeos curtos é muito menor.
  • Definir limite de novas tentativas: dê a cada tarefa um número máximo de tentativas; ao ultrapassar, intervenha manualmente ou troque o material, evitando que novas tentativas automáticas consumam o orçamento.
  • Registrar cada chamada: registre duração, se houve nova tentativa e motivo da falha. Sem esses dados, você não consegue distinguir se o estouro de orçamento vem do prompt ou do material.

Preços em tempo real e detalhes de cobrança seguem o painel de preços do site do HiAPI.ai; este artigo discute apenas o método de estimativa.

Ideias de preparação e ajuste do material de referência

Nesta cadeia do reference-to-video, o impacto da qualidade do material no vídeo final costuma ser maior do que o ajuste fino de parâmetros. A razão é: os parâmetros ajustam a "tendência" do modelo, enquanto o material determina a "base" do modelo. Se a base não é clara, a melhor tendência não se concretiza.

O que é um bom material de referência

  • Sujeito claro: o espectador consegue perceber em meio segundo "o que deve ser preservado" na imagem. Fundo poluído e sujeito pequeno enfraquecem o efeito da referência.
  • Características estáveis: a aparência do mesmo sujeito deve ser consistente entre diferentes imagens de referência. Se várias imagens de referência já são contraditórias entre si (cor, forma e material não batem), o modelo só pode oscilar entre versões.
  • Iluminação e ângulo razoáveis: iluminação extrema e ângulos com distorção severa transmitem pistas visuais erradas ao modelo.
  • Limpo: remova marcas d'água, adesivos e textos extras. Esses elementos podem ser adotados como características do sujeito.

Prioridade do ajuste

Quando o resultado não é ideal, recomenda-se investigar nesta ordem, em vez de mexer nos parâmetros logo de início:

  1. Primeiro troque o material: substituir a imagem de referência por uma versão mais nítida e com sujeito mais único costuma ser o meio mais rápido de melhoria.
  2. Depois altere o prompt: explicite ação e ambiente, e remova descrições repetidas da imagem de referência.
  3. Só por último mexa nos parâmetros: considere ajuste fino após estabilizar as duas etapas anteriores, alterando apenas uma variável por vez para facilitar a atribuição de causa.

Consistência entre múltiplas imagens de referência

Se você fornecer várias imagens de referência, garanta que sejam "do mesmo sujeito". Misturar indivíduos diferentes ou imagens de estilos diferentes é uma das causas mais comuns de deriva no resultado. É melhor fornecer uma a menos do que fornecer uma imagem contraditória.

Criar uma linha de base de material

Recomenda-se criar um conjunto fixo de material de referência para o seu sujeito principal, como linha de base para todas as gerações posteriores. A cada geração, parta dessa linha de base e altere apenas o prompt; assim você consegue distinguir claramente "problema de material" de "problema de descrição" e também facilita a unificação de estilo entre vários vídeos.

Falhas comuns e direções de solução de problemas

A maioria dos problemas na fase de integração pode ser classificada em alguns padrões fixos. Investigar na ordem abaixo costuma ser mais rápido do que tentar repetidamente às cegas.

1. Requisição rejeitada ou erro de parâmetro retornado

Primeiro confirme se o identificador de capacidade está correto, se os campos obrigatórios de material de referência estão completos e se o formato do material é aceito pela interface. Os nomes de campo seguem a documentação; não adivinhe por experiência.

2. Tarefa sem resultado por muito tempo

A geração de vídeo é uma tarefa assíncrona; confirme primeiro se você está obtendo o resultado pelo identificador da tarefa, em vez de esperar em uma requisição síncrona. Se realmente houver timeout, verifique se o volume do material é grande demais.

3. O resultado "não se parece" com o material de referência

Este é o problema mais frequente; a ordem de investigação é: material está nítido → há imagens de referência contraditórias → o prompt descreve conteúdo conflitante com a imagem de referência. Na maioria dos casos, não é o modelo que falha, mas o material que não está adequado.

4. O sujeito deriva entre trechos

A causa costuma ser o uso de materiais de referência diferentes em cada trecho, ou descrições inconsistentes do sujeito no prompt de cada trecho. Fixar um conjunto de material de linha de base e unificar a descrição do sujeito melhora significativamente.

5. A ação da imagem não corresponde ao esperado

O prompt carece de instruções claras de ação e câmera, e o modelo só pode improvisar. Escreva claramente "o que fazer, como se mover, onde está a câmera".

6. Custo acima do esperado

Reveja os logs de chamada: a duração foi configurada longa demais ou a taxa de nova tentativa está alta? No primeiro caso, ajuste a estratégia de duração no produto; no segundo, volte ao material e ao prompt para buscar a causa.

Princípio básico de solução de problemas

Altere apenas uma variável por vez e mantenha logs. Se alterar material e prompt ao mesmo tempo, mesmo que o resultado melhore, você não saberá qual item funcionou, e na próxima vez que encontrar um problema semelhante terá que testar desde o início.

Lista de verificação antes da integração e próximos passos

Antes de escalar formalmente, recomenda-se validar item por item conforme a lista abaixo, mantendo os riscos na fase de baixo volume.

Lista de verificação antes do lançamento

  • Capacidade adequada: confirme que o seu cenário realmente precisa de reference-to-video, e não de text-to-video ou image-to-video.
  • Linha de base de material pronta: o sujeito principal tem um conjunto fixo e limpo de material de referência.
  • Prompt com modelo: as descrições de ação, câmera e ambiente têm estrutura reutilizável, em vez de improviso a cada vez.
  • Cadeia assíncrona funcionando: envio, polling ou callback, validação de resultado e nova tentativa em caso de falha; as quatro etapas têm código e passaram por teste de carga.
  • Novas tentativas com limite: a nova tentativa automática tem número máximo; ao ultrapassar, entra na fila manual.
  • Custo com painel: com base nos registros de chamada de duração e número de tentativas, é possível calcular o gasto real a qualquer momento.
  • Estratégia de duração clara: o produto impõe restrições à duração gerável, evitando que o usuário alongue arbitrariamente e cause perda de controle de custos.

Do baixo volume à escala

O caminho recomendado é: primeiro executar ponta a ponta com requisições construídas manualmente, validando a eficácia do material e do prompt; depois fazer testes em pequeno lote com a duração mais curta, medindo taxa de nova tentativa e taxa de disponibilidade; após confirmar a estabilidade dos indicadores, ampliar gradualmente a concorrência e a duração. Mantenha capacidade de reversão em cada etapa.

Indicadores-chave

Na fase de escala, o que realmente precisa ser monitorado são a taxa de disponibilidade na primeira tentativa e o número médio de tentativas. O primeiro determina a experiência do usuário, e o segundo determina diretamente o custo. Só depois que esses dois indicadores se estabilizarem é que se pode falar em expandir duração e concorrência.

Se ainda não começou a colocar a mão na massa, consulte primeiro no HiAPI.ai os detalhes do modelo vidu-q3-mix/reference-to-video e o preço em tempo real, e então decida a duração do primeiro vídeo a gerar.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API