Como criar vídeos curtos com o kling-3.0/motion-control na API hiapi

Se você já tentou fazer o personagem de um vídeo gerado executar um movimento específico — não "dançar", mas esta dança específica deste clipe específico — sabe que as opções de sempre são ruins: rotoscopar quadro a quadro manualmente, retreinar um modelo de movimento ou simplesmente desistir e aceitar o que o prompt de texto lhe der. O kling-3.0/motion-control dispensa tudo isso. Você fornece uma imagem de personagem e um vídeo de referência, e ele transfere o movimento e as expressões da referência para o seu personagem — sem rigging, sem keyframes, sem traje de captura de movimento.

Este artigo percorre um fluxo de trabalho real de vídeo curto: primeiro, transforma uma foto de motorista em um clipe de referência curto e, em seguida, usa esse clipe via motion-control para animar uma imagem de personagem completamente diferente. Cada requisição abaixo é uma chamada real à API /v1/tasks da hiapi, cada material foi gerado durante a escrita deste artigo (nada foi emprestado de galerias de demonstração de fornecedores) e cada preço foi obtido em tempo real do endpoint de preços da hiapi.

O que o kling-3.0/motion-control realmente faz

O modelo recebe duas entradas:

• image_url — um retrato de personagem único (o "alvo"). Isso determina quem aparece na saída.
• video_url — o clipe de referência de movimento, de 3 a 30 segundos. Isso determina o que ele faz.

A saída é um vídeo do personagem alvo executando os movimentos e expressões faciais do vídeo de referência, renderizado em 720p ou 1080p. Ele não aceita prompt de texto, duração nem proporção de tela — a composição da saída segue diretamente o clipe de referência, e a duração da saída acompanha a duração do clipe de entrada (nossa referência de 3 segundos retornou uma saída de 3,03 segundos).

Esse contrato estreito com apenas duas entradas é justamente o que o torna útil para conteúdo de vídeo curto: você não precisa de equipamento de captura de movimento para dar uma performance convincente a um mascote de marca, personagem de produto ou avatar estilizado — você só precisa de qualquer vídeo de uma pessoa fazendo o movimento que deseja.

O que você precisa ter em mãos

• Uma chave de API da hiapi (Authorization: Bearer <key>)
• Uma imagem de personagem acessível publicamente via HTTPS (não é o seu alvo — é o seu personagem condutor)
• Uma segunda imagem de personagem, que será o alvo real que você quer animar
• ffmpeg/ffprobe caso queira extrair o quadro de capa ou verificar a duração do clipe localmente, como fizemos neste artigo

Demonstração real: um clipe de movimento, dois personagens diferentes

O ponto central do motion-control é que o vídeo de referência e o personagem final não precisam combinar. Para provar isso, esta demonstração usou três etapas de geração:

1. Um retrato de motorista, animado em um clipe de referência curto:

Esse retrato se tornou um clipe de movimento de 3 segundos em 480p via grok-imagine-1.5/image-to-video — uma forma rápida e barata de fabricar um clipe de referência a partir de uma imagem estática, em vez de procurar um clipe pronto:

2. Um personagem alvo completamente diferente — o mesmo movimento, aparência totalmente distinta:

3. Alimente ambos no motion-control. O vendedor executa exatamente o mesmo movimento de virar e olhar para trás do entregador:

Esse é o fluxo de trabalho inteiro: gere (ou obtenha) qualquer clipe de movimento que quiser, aponte o motion-control para uma imagem de personagem totalmente não relacionada e obtenha esse personagem executando o movimento. Para pipelines de vídeo curto, isso significa que uma biblioteca de movimentos de referência pode impulsionar um número ilimitado de personagens, sem precisar refilmar ou refazer a animação de referência a cada vez.

Requisição mínima funcional (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/target-character.png",
      "video_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/motion-reference.mp4",
      "resolution": "720p"
    }
  }'

Resposta (tarefa criada, ainda em processamento):

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "pending"
  },
  "success": true
}

Faça polling até a conclusão:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Na nossa execução, um clipe de 3 segundos em 720p levou cerca de 2,3 minutos do início ao fim (o status alternou para handling cerca de uma dúzia de vezes antes de mudar para success) — ao projetar seu loop de polling, reserve alguns minutos, não alguns segundos. Resposta final:

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "success",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M4CWNSYA7RB637YJ2QZMHMMS-0.mp4",
        "storage": "temp",
        "expireAt": 1792039027
      }
    ]
  },
  "success": true
}

Esse output[0].url é um link temporário — expireAt é um timestamp Unix e, no nosso teste, a validade era de cerca de 24 horas. Baixe e re-hospede imediatamente; não linke diretamente para ele em nada que você publicar.

O mesmo fluxo em Python

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def create_motion_control_task(image_url: str, video_url: str, resolution: str = "720p") -> str:
    resp = requests.post(
        API_BASE,
        headers=HEADERS,
        json={
            "model": "kling-3.0/motion-control",
            "input": {
                "image_url": image_url,
                "video_url": video_url,
                "resolution": resolution,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 600, poll_every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = create_motion_control_task(
        image_url="https://your-cdn.example.com/target-character.png",
        video_url="https://your-cdn.example.com/motion-reference.mp4",
        resolution="720p",
    )
    output_url = wait_for_result(task_id)

    video_bytes = requests.get(output_url, timeout=120).content
    with open("motion-control-output.mp4", "wb") as f:
        f.write(video_bytes)
    print(f"saved {len(video_bytes)} bytes")

Nada complicado — crie a tarefa, faça polling de GET /v1/tasks/{taskId} em intervalos, baixe output[0].url no momento em que mudar para success e re-hospede por conta própria antes que o link temporário expire.

Os parâmetros que o motion-control realmente valida

O schema é rigoroso — qualquer coisa além desses três campos é rejeitada, e vale a pena saber disso de antemão em vez de descobrir por tentativa e erro:

Campo	Obrigatório	Descrição
image_url	Sim	URL HTTPS pública, personagem alvo
video_url	Sim	URL HTTPS pública, referência de movimento de 3 a 30 segundos
resolution	Não (tem valor padrão, mas vale definir)	"720p" ou "1080p" — isso também determina a faixa de preço

Campos que você talvez espere de outros modelos de vídeo — duration, aspect_ratio, prompt — são rejeitados com um erro de schema:

{
  "code": 1,
  "message": "input: Object { input } has unexpected additional properties: duration, aspect_ratio",
  "success": false
}

Isso é intencional: a duração e a composição da saída herdam integralmente do vídeo de referência, então duration/aspect_ratio não têm o que controlar. Se você quiser uma saída mais longa ou com composição diferente, corte ou recomponha o clipe de referência antes de enviar, em vez de modificar a requisição.

Preços: cobrança por segundo de saída, não por requisição

Diretamente do endpoint de preços da hiapi:

Resolução	Preço
720p	$0,10 / segundo de saída
1080p	$0,172 / segundo de saída

A cobrança é determinada pela duração real da saída (estimated_seconds), que reflete a duração do seu clipe de referência — e não uma taxa fixa por requisição. Nossa referência de 3 segundos em 720p gerou uma saída de 3,03 segundos, custando cerca de $0,30. Um clipe de referência de 10 segundos em 1080p fica em torno de $1,72. Se você for usar isso em lote em um calendário de conteúdo, a alavanca prática é a duração da referência: referências mais curtas custam menos e ainda entregam a performance de movimento completa para formatos de vídeo curto (Reels, TikTok, Shorts), nos quais 3 a 8 segundos muitas vezes já é o clipe inteiro.

Considerações de produção

• Escolha a composição do clipe condutor com intenção. A saída herda a proporção de tela, a distância de câmera e o ritmo do vídeo de referência — uma referência em close-up gera uma saída em close-up, independentemente de como a imagem do personagem alvo foi cortada.
• Expressões claras transferem melhor do que expressões sutis. Um giro, um aceno ou uma inclinação de cabeça bem marcados na referência aparecem de forma confiável no personagem alvo; microexpressões muito sutis e naturais são mais difíceis de o modelo identificar e transferir.
• Reutilize um clipe de referência em muitos personagens. Como video_url e image_url são totalmente independentes, o padrão mais eficiente em um pipeline de conteúdo é: primeiro montar uma pequena biblioteca de movimentos de referência e depois rodar o mesmo clipe com muitas imagens de personagens diferentes.
• As URLs de saída temporárias têm validade curta. O expireAt costuma ser de cerca de um dia — baixe e re-hospede imediatamente, em vez de agendar o download para depois.
• O processamento não é instantâneo. Neste teste, um clipe de 3 segundos em 720p levou mais de dois minutos do início ao fim; planeje seu loop de polling e qualquer automação subsequente em escala de minutos (e não de segundos, como costuma ser o caso em chamadas de geração de imagem a partir de texto).

Conteúdo relacionado

• Página do modelo kling-3.0/motion-control
• Preços da hiapi
• Documentação da API hiapi

Tem um clipe de referência e um personagem que quer combinar? Obtenha uma chave na página de preços e aponte a requisição curl acima para o seu próprio image_url/video_url — todo o loop acima pode ser copiado e colado diretamente.

Perguntas frequentes

Posso usar qualquer vídeo como referência de movimento? Qualquer vídeo com um performer humano (ou humanoides) claro serve, desde que esteja publicamente acessível via HTTPS e tenha de 3 a 30 segundos de duração. Ele não precisa conter o seu personagem alvo — é justamente esse o ponto do modelo.

A saída preserva o fundo do vídeo de referência? Não — a aparência do personagem, incluindo o ambiente sugerido pela imagem alvo, é mantida; o vídeo de referência fornece o movimento e as expressões, não o conteúdo do cenário.

Por que minha requisição foi rejeitada com "unexpected additional properties"? O schema aceita apenas image_url, video_url e resolution. Campos como duration, aspect_ratio ou prompt não fazem parte da entrada desse modelo e retornam 400 imediatamente — remova-os do payload.

Quanto tempo leva uma tarefa de motion-control? Reserve alguns minutos por clipe. Nosso exemplo de 3 segundos em 720p levou cerca de 2,3 minutos desde a criação da tarefa até a saída success disponível para download.

Posso controlar a resolução da saída independentemente do preço? Não — resolution é tanto a configuração de qualidade da saída quanto o seletor de faixa de preço: "720p" é cobrado a $0,10/segundo de saída, e "1080p" a $0,172/segundo de saída.