API Runway para texto-para-vídeo: guia do desenvolvedor para chamar o Gen-4.5 via hiapi

Por que usar um endpoint gerenciado de texto-para-vídeo

Texto-para-vídeo não é um substituto para fluxos de geração ou edição de imagens — é uma capacidade fundamental diferente. Um modelo de imagem entrega um quadro estático, que você pode recortar, retocar ou compor. Uma chamada de texto-para-vídeo entrega movimento: movimento de câmera, ação do sujeito e luz que muda ao longo do tempo. Se o seu produto precisa de um clipe de vídeo — uma peça curta de marketing, um loop de fundo dentro do app, uma prévia de uma cena — uma única chamada de "requisição a clipe" costuma ser o caminho mais rápido da ideia ao material.

O preço é o controle. Você descreve o movimento em palavras, em vez de defini-lo com quadros-chave, então o modelo precisa interpretar sozinho. Isso torna a qualidade do prompt mais importante do que em tarefas de imagem, e também torna o ciclo de iteração mais importante do que uma tentativa única.

Um endpoint gerenciado oferecido via hiapi elimina o trabalho de infraestrutura em torno dessa capacidade fundamental: você obtém uma interface consistente, um modelo de credenciais e uma estrutura de resposta unificada entre os modelos de vídeo que você chama. Você gasta seu tempo em prompts e integração de produto, não em pipelines de armazenamento, polling de tarefas e SDKs de cada fornecedor.

Cenários adequados:

• Clipes curtos gerados sob demanda a partir de entrada do usuário ou de templates
• Exploração rápida de conceitos antes de investir em um pipeline de produção completo
• Fundos e material de B-roll que ainda sejam utilizáveis mesmo se uma geração tiver pequenas falhas

Cenários inadequados: qualquer necessidade de continuidade precisa no nível do quadro, saída determinística ou coerência narrativa longa. Reserve orçamento para vários clipes candidatos por resultado utilizável.

A estrutura do endpoint runway-gen-4.5/text-to-video

Conceitualmente, uma requisição para runway-gen-4.5/text-to-video tem três partes: o prompt, as configurações da requisição e sua identidade/autorização. Apenas a primeira é criativa; as outras duas determinam como o modelo roda e como a cobrança é feita.

O que você envia

• A string do prompt. A principal entrada criativa — descreva em linguagem natural o sujeito, a ação, a câmera, a luz e a atmosfera.
• Configurações da requisição. Proporção de tela, duração e quaisquer flags de geração expostas pelo endpoint. Elas determinam a forma do contêiner de saída, não o conteúdo.
• Cabeçalho de autenticação. Sua chave hiapi, incluída em cada chamada. Trate-a como segredo; nunca a publique em código do cliente.

O que você recebe

A geração de vídeo não é instantânea, então, dependendo de como o endpoint é chamado, você pode receber um handle de tarefa que precisa ser consultado por polling, ou uma resposta que resolve para uma URL de mídia. Em qualquer caso, você recebe uma referência ao clipe gerado, não os bytes brutos inline. Se precisar usar o material após o prazo de validade da URL retornada, baixe-o e persista-o no seu próprio armazenamento.

Um modelo mental útil: o endpoint é uma função que mapeia (prompt, settings) para um clipe mais metadados. Sua integração deve tratá-lo como assíncrono, repetível e não determinístico — as mesmas entradas nem sempre produzem o mesmo clipe, e isso é comportamento esperado, não um defeito.

Mantenha a construção da requisição simples e entediante. Escreva um pequeno wrapper interno que monta o corpo da requisição, anexa a autenticação, envia a chamada e normaliza a resposta para { status, videoUrl, error }. Todas as seções seguintes deste guia presumem que esse wrapper já existe.

Escrevendo prompts cinematográficos que funcionam em movimento

Adjetivos vagos desmoronam em movimento. "A beautiful cinematic shot of a city" não dá ao modelo nada para animar, então ele gera algo genérico e à deriva. A solução é especificar os quatro elementos de que um cinegrafista precisa: sujeito, câmera, luz e movimento.

Nomeie o sujeito e a ação

Diga o que está na cena e o que ele faz ao longo do clipe. Dê um ponto de partida e um ponto final implícito para o modelo ter uma trajetória de movimento a seguir.

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

Especifique a câmera explicitamente

Use linguagem de câmera que o modelo consiga mapear para movimento: aproximação lenta, plano aberto fixo, acompanhamento na mão, tracking em ângulo baixo, panorâmica lenta para a direita, descida aérea. Apenas um movimento de câmera por clipe é mais seguro do que três movimentos em conflito.

Static wide shot, camera at ground level, no zoom.

Especifique a luz e a hora

A luz determina a maior parte do nível de produção percebido. Dê a fonte e a textura: luz do dia difusa e encoberta, sol forte de fim de tarde vindo da esquerda da câmera, neon prático em reflexos molhados à noite.

Descreva movimentos fisicamente plausíveis

Movimentos rápidos em clipes curtos viram borrão. Prefira uma única ação legível em velocidade moderada a muitos eventos rápidos. Se quiser tensão, obtenha-a do movimento de câmera e da luz, em vez de fazer uma dúzia de coisas acontecerem ao mesmo tempo.

Mantenha um único parágrafo

Um parágrafo compacto de uma a três frases vence uma lista de especificações em tópicos. Escreva como uma descrição de cena, não como uma lista de desejos. Evite empilhar adjetivos de estilo; escolha um visual e mantenha-o até o fim.

Um template confiável:

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

Reescreva seu prompt dentro desse template antes de alterar qualquer configuração.

Uma requisição executável, passo a passo

Este passo a passo pressupõe Node.js e uma função de wrapper, mas a estrutura não depende de linguagem.

Passo 1: escreva a cena

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

Passo 2: escolha as configurações da requisição

Escolha a proporção de tela que corresponde ao local final onde o clipe será usado, e a duração mais curta que ainda conte a história. Clipes curtos falham rápido e custam menos para explorar.

Passo 3: envie a chamada

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

Passo 4: obtenha o clipe

Se a resposta trouxer um handle de tarefa, faça polling em intervalos pequenos com backoff até atingir um estado terminal. Se já trouxer uma URL de mídia diretamente, pule para o Passo 5.

Passo 5: persista o material

Baixe o clipe e armazene-o com suas próprias chaves. Trate a URL retornada como endereço temporário.

Passo 6: registre os pontos de decisão

Registre o prompt, as configurações e o material gerado juntos. É esse log que torna a próxima seção — ajuste fino — acionável em vez de adivinhação.

Ajustando a saída sem reescrever o prompt

Quando o clipe decepciona, o reflexo é reescrever o prompt. Segure-se por uma rodada. Prompt e configurações são variáveis independentes, e mudar os dois ao mesmo tempo destrói sua capacidade de julgar qual deles foi decisivo.

Isole variáveis

Mantenha o prompt fixo e mude exatamente uma configuração de requisição — proporção de tela, duração ou alguma flag de geração. Rode de novo. Se o clipe melhorar, o problema era estrutural, não criativo. Se não melhorar, reverta essa configuração e passe a editar o prompt.

Resolva problemas estruturais com configurações

• Composição não bate com o local de exibição? Mude a proporção de tela.
• A ação é cortada antes de terminar? Aumente a duração.
• Tudo à deriva, sem âncora? Encurte o clipe para que ele não tenha tanto tempo para derivar.

Resolva problemas de conteúdo com edições no prompt

• Sujeito errado ou ausente? Nomeie-o mais cedo e seja específico.
• Câmera vagando? Remova todas as palavras de câmera exceto o único movimento que você quer.
• Sem vida, chapado? Adicione uma fonte de luz e uma direção.

Faça um pequeno teste A/B

Fixe um prompt-semente, gere três variantes, cada uma mudando apenas uma cláusula. Compare-as lado a lado, não de memória. A não determinabilidade significa que um único clipe ruim não é evidência; procure um padrão em duas ou três execuções antes de concluir que uma cláusula é prejudicial.

Anote as conclusões no log que você já mantém. Depois de uma dúzia de iterações, isso vira um manual de prompts e configurações específico do seu produto, muito mais valioso que qualquer lista genérica de prompts.

Depurando falhas comuns

A maioria das falhas da primeira semana se enquadra em quatro categorias. Cada uma tem um caminho de investigação diferente.

Requisição rejeitada ou bloqueada

Uma resposta não-2xx com informação de política significa que o prompt ou as configurações não foram aceitos. Leia o corpo do erro em vez de tentar de novo às cegas. Reescreva a descrição problemática, remova pessoas reais nomeadas ou marcas, e reenvie. Registre o prompt rejeitado como estava — rejeições recorrentes costumam remontar a um hábito no seu template de prompt.

Timeout

A geração de vídeo é lenta. Se seu cliente HTTP der timeout antes de o endpoint responder, a tarefa ainda pode estar rodando e será cobrada. Aumente o timeout do cliente para chamadas de geração e mova o polling para um worker em segundo plano, em vez de manter a requisição pendurada.

Clipe vazio ou inutilizável

Uma resposta bem-sucedida, mas sem sujeito reconhecível no clipe, normalmente significa que o prompt era abstrato demais. Releia-o contra o template sujeito-câmera-luz-movimento. Se um dos quatro estiver faltando, é aí que você corrige.

Erros de autenticação e configuração

401 e 403 significam problema de chave, não de prompt. Confirme que a chave existe no ambiente de execução, e não apenas no seu shell local, e confirme o formato do cabeçalho. Quanto mais cedo esse tipo de falha é detectado, mais barato é; em produção, ele é caro.

Uma regra geral: classifique o erro antes de mudar qualquer coisa. Erros de prompt, erros de configuração e erros de infraestrutura exigem correções diferentes, e misturá-los desperdiça orçamento de geração.

Custo, latência e proteções de produção

Antes de ir ao ar, decida como o endpoint se comporta em caso de falha, porque a geração de vídeo costuma ser a chamada mais cara e mais lenta da maioria dos produtos.

Orçamente por clipe, não por chamada

A cobrança de vídeo normalmente é atrelada ao comprimento da saída, então clipes mais longos custam mais que clipes curtos. Faça o orçamento por unidade de clipe finalizado — incluindo tentativas e candidatos rejeitados — em vez de contar chamadas de API. Defina um teto de geração por usuário e por sessão. Consulte o painel de preços para as tarifas atuais; não as codifique na lógica de negócio.

Projete para latência

Nunca deixe uma requisição voltada ao usuário bloquear na geração. Inicie a tarefa, retorne um handle imediatamente e entregue o clipe por polling, webhook ou notificação. Mostre progresso na UI para que uma renderização lenta pareça trabalho em andamento, não travamento. Faça cache dos clipes gerados por prompt e configurações, para evitar regenerar a partir de requisições repetidas.

Valide antes de gerar

Uma verificação barata antes da chamada poupa um tratamento caro depois:

• Imponha comprimento mínimo e máximo do prompt no seu wrapper
• Rejeite prompts sem sujeito ou sem ação
• Valide a proporção de tela contra o alvo de renderização
• Confirme que o usuário está dentro da cota dele

Modere na entrada e na saída

Faça uma checagem de texto no prompt antes de enviar. Faça uma checagem leve no clipe retornado antes de exibi-lo. Ambos são mais baratos que um incidente de suporte.

Mantenha um plano de contingência

Se a geração falhar ou demorar demais, entregue um quadro de capa estático ou um clipe placeholder em vez de um erro. O recurso deve degradar, não quebrar.

Comece com um endpoint, um wrapper e um log; vá adicionando proteções conforme aprende onde o produto realmente falha, e mantenha o painel de preços como fonte única de verdade para custos.