Tutorial

Controle de primeiro e último quadro em vídeos de IA: guia de movimento preciso entre modelos no hiapi

Sep 4, 2026

A maioria das APIs de imagem para vídeo recebe apenas uma imagem estática e então improvisa o movimento. Apenas alguns modelos permitem fixar o ponto final da tomada, não apenas o inicial — você fornece o primeiro e o último quadro, e o modelo interpola o movimento entre eles. É exatamente essa a diferença entre "fazer esta foto se mexer" e "realizar precisamente esta transição".

O problema é que o suporte ao controle de último quadro varia entre os modelos, e mesmo dentro da linha de um mesmo fornecedor as variantes topo de linha e rápida/turbo podem diferir. Este tutorial deixa claro quais modelos de vídeo do hiapi suportam apenas controle de primeiro quadro e quais suportam primeiro + último quadro, e apresenta os campos de entrada reais (e nada uniformes) de cada um, para que você não descubra, depois de muito esforço, que o modelo escolhido ignorou silenciosamente o seu último quadro.

1. O que você precisa preparar

Uma chave de API do hiapi obtida no console (sk-...) e duas URLs de imagem acessíveis pelo modelo de destino (URLs HTTPS públicas — o endpoint de tarefas não aceita upload de arquivos locais). Todos os modelos abaixo são chamados pela mesma API de tarefas unificada, então, desde que sua chave funcione para um deles, funcionará para todos.

2. Exemplo mínimo executável

Toda a geração de vídeo no hiapi usa o mesmo endpoint: crie a tarefa e depois consulte-a repetidamente (ou use callback — veja Padrões de produção) até atingir um estado terminal.

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video é o exemplo mais típico desse padrão: input.image_urls aceita uma ou duas URLs de imagem. Se você enviar uma, o modelo ancora apenas o primeiro quadro e o restante fica livre; se enviar duas, a segunda URL se torna o último quadro obrigatório — o modelo é informado de onde a tomada deve terminar. A duração é um inteiro de 3–15 (segundos), resolution é 720p / 1080p / 4k, e o booleano opcional sound adiciona áudio ambiente gerado. Aqui não há campo aspect_ratio — a proporção da saída segue os quadros fornecidos.

Nem todos os modelos têm essa estrutura. seedance-2.5/image-to-video obtém o mesmo efeito por meio de dois campos com nomes separados, em vez de um array:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url só faz sentido quando pareado com first_frame_url — você pode enviar apenas first_frame_url para uma tomada só com primeiro quadro, mas não o contrário. Esse modelo aceita durações de 4–30s, resolução de no máximo 720p/1080p (sem nível 4K), e aspect_ratio tem como padrão adaptive, ou seja, segue o primeiro quadro, em vez de valores explícitos 16:9/9:16.

Os nomes dos campos realmente diferem entre os modelos — image_urls versus first_frame_url/last_frame_url — portanto, cada troca de modelo deve ser tratada como uma mudança de schema, e não como uma substituição direta.

Nem todo modelo suporta

veo-3.1/image-to-video recebe uma única string image_url e não tem parâmetro de último quadro algum — você pode definir aspect_ratio (auto/16:9/9:16), resolution e uma enumeração fixa de duration (4, 6 ou 8 segundos), mas não pode fixar o quadro final. O mesmo ocorre com o nível inferior da linha Kling: kling-3.0-turbo/image-to-video (a versão rápida/mais barata do kling-3.0-omni) aceita no máximo um item em image_urls — sem último quadro e sem resolução 4K. Se você precisa de controle de último quadro, escolha o nível topo de linha ou um modelo criado especificamente para isso (como seedance-2.5), em vez de supor pelo nome da família do modelo.

3. Padrões de produção

Em escala, use callback em vez de polling. No mesmo corpo da requisição, passe um objeto callback em vez de consultar em loop:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" dispara uma única vez, quando a tarefa atinge qualquer estado terminal — tanto succeeded quanto failed são terminais, então seu handler de webhook deve deduplicar por taskId, em vez de assumir que o callback representa apenas sucesso. O polling com GET /v1/tasks/:id é mais adequado para depuração local, chamadas únicas de baixa frequência, ou como contingência de reconciliação quando o callback nunca chega (instabilidade de rede, seu endpoint temporariamente fora do ar).

Idempotência. Retentativas após timeout ou conexão interrompida podem criar tarefas duplicadas se feitas sem cuidado — registre o id da tarefa retornado pela chamada de criação e, antes de considerar enviar uma nova tarefa, faça um GET desse id como retentativa.

As URLs de saída expiram. O campo expireAt em cada entrada de saída não é decorativo — quer você saiba do sucesso da tarefa por callback ou por polling, baixe o vídeo e persista-o (salve no seu próprio armazenamento) o quanto antes.

Falha de autenticação. Uma chave incorreta ou ausente retorna HTTP 401 e {"error": {"code": "permission_denied", ...}}. Verifique explicitamente esse status/código de erro, em vez de assumir que qualquer resposta não-2xx significa falha na própria geração — no tratamento de erros, é valioso distinguir "minha chave está errada" de "o modelo rejeitou minha entrada", porque as correções são completamente diferentes.

4. Páginas relacionadas

Página do modelo Kling 3.0 Omni de imagem para vídeo —— preços, experiência online e referência completa de parâmetros do modelo usado nos exemplos acima.
Página do modelo Seedance 2.5 de imagem para vídeo —— a variante com first_frame_url/last_frame_url.
Documentação de autenticação —— como funcionam o cabeçalho Authorization: Bearer sk-... e o escopo das chaves.
Documentação de criação de tarefas —— referência completa de requisição/resposta de /v1/tasks, incluindo opções de callback.
Preços do hiapi —— preços atuais por segundo e por resolução (a cobrança varia conforme o modelo e a resolução; consulte a página ao vivo em vez de números fixos).

5. Perguntas frequentes

Quais modelos de vídeo do hiapi suportam controle de último quadro? kling-3.0-omni/image-to-video (por meio do array image_urls com 2 itens) e seedance-2.5/image-to-video (por meio de first_frame_url + last_frame_url) atualmente suportam. veo-3.1/image-to-video e kling-3.0-turbo/image-to-video não suportam — eles aceitam apenas um único quadro inicial.

É possível especificar apenas o último quadro sem fornecer um prompt? Ambos os modelos ainda aceitam (e geralmente esperam) um prompt além dos quadros — ele orienta o movimento entre os dois quadros, não apenas o conteúdo. Nem todo modelo rejeita diretamente um prompt vazio ou ausente, mas descrever explicitamente a transição torna o movimento mais previsível.

Os dois quadros precisam ter a mesma proporção? Nem kling-3.0-omni/image-to-video nem seedance-2.5/image-to-video oferecem um aspect_ratio explícito independente da configuração das imagens — a proporção da saída segue os quadros de entrada, portanto proporções inconsistentes entre o primeiro e o último quadro produzem um resultado visivelmente estranho, em vez de um erro. Antes de enviar, corte ou preencha os dois quadros para a mesma proporção.

O que acontece se eu enviar apenas o último quadro sem o primeiro? Nenhum dos dois modelos suporta isso — no seedance-2.5, last_frame_url só pode ser usado junto com first_frame_url; o array do kling-3.0-omni é lido por posição (primeiro item = primeiro quadro). Não existe um modo "inverso" que especifique apenas o quadro final.

Controle de último quadro equivale à transferência de movimento de vídeo para vídeo? Não — essa é outra capacidade (seedance-2.5/reference-to-video no hiapi, que recebe um vídeo de referência para conduzir o movimento ou o movimento de câmera, em vez de duas imagens estáticas). O controle de primeiro/último quadro interpola entre duas imagens; o vídeo para vídeo com referência imita o padrão de movimento de um clipe existente.

Adicionar um último quadro custa mais caro do que gerar só com o primeiro? Ambos os modelos cobram por segundo e por resolução, não por imagem de entrada, portanto adicionar um último quadro não aumenta o custo por si só — consulte a página de preços para as tarifas atuais.