Blogue

Tutorial

Como usar o kling-3.0/motion-control com a API HiAPI: exemplos em curl e Python

Nov 12, 2026
Imagem de capa: sobre um fundo em tom de carvão quente, uma ampla faixa de luz âmbar atravessa na diagonal, com bordas nítidas e algumas formas geométricas escuras pontuando a parte inferior.
Nesta página

Para que serve o kling-3.0/motion-control e quando escolhê-lo

O controle de movimento é um tipo de capacidade na geração de vídeo: você entrega um vídeo de referência ao modelo, e ele conduz o movimento, o ritmo e a composição da saída, em vez de depender apenas de um prompt de texto para descrever a ação. Ao usar o kling-3.0/motion-control na API HiAPI, o vídeo de referência é a entrada principal: ele ancora como o objeto se move, e os demais parâmetros moldam o conteúdo gerado em torno desse movimento.

Quando o movimento em si é o desafio, este é o modelo a escolher. Cenários típicos de uso:

  • Você tem um vídeo curto e quer reproduzir seu movimento de câmera ou a ação do sujeito com um conteúdo diferente.
  • Você precisa de um movimento previsível, em vez de resultados de texto-para-vídeo que dependem da sorte do prompt de texto.
  • Você está construindo um pipeline em que o movimento é um ativo reutilizável entre várias gerações, portanto deve ser uma entrada e não uma frase descritiva.

Se você só precisa de texto-para-vídeo e não tem referência de movimento, o controle de movimento apenas adiciona uma etapa de upload e restrições de entrada mais rígidas, sem benefício. Da mesma forma, se o vídeo de referência for longo ou tiver composição instável, espere mais tentativas. O restante deste guia assume que você já determinou que o controle de movimento é a ferramenta adequada e deseja uma forma de integração confiável e reproduzível.

Pré-requisitos e configuração do endpoint

Antes da primeira chamada, prepare três coisas.

1. Chave de API

Crie uma chave no console da sua conta HiAPI.ai e guarde-a em uma variável de ambiente, em vez de gravá-la no código-fonte:

export HIAPI_API_KEY="your_api_key_here"

Envie-a em cada requisição como bearer token: Authorization: Bearer $HIAPI_API_KEY.

2. Convenção de URL base

Todas as chamadas HiAPI compartilham a mesma URL base e um prefixo de caminho com versão. Coloque a URL base na configuração, para que alternar de ambiente não exija alterar os pontos de chamada:

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. Identificador do modelo

O modelo é selecionado por requisição pelo campo model, com o identificador exato kling-3.0/motion-control. Não o codifique em vários lugares — passe-o como uma constante, para que trocar de modelo no futuro exija alterar apenas uma linha.

Você também precisa de um local hospedado de onde a API possa buscar o vídeo de referência. Normalmente usa-se uma URL assinada com validade limitada; garanta que ela possa ser acessada sem cabeçalhos personalizados ou cookies.

Com esses três itens prontos, o trabalho restante é a estrutura da requisição e o ciclo de vida da tarefa.

Fornecer o vídeo de referência e os parâmetros de movimento

Uma requisição de controle de movimento se divide conceitualmente em duas metades: a fonte do movimento (seu vídeo de referência) e as configurações de geração (o que o modelo deve produzir).

Vídeo de referência

O vídeo de referência vai no corpo da requisição como URL, e não como bytes brutos no payload JSON. Duas regras práticas:

  • Use uma URL que permaneça válida durante toda a fila e o processamento da tarefa. URLs assinadas que expiram cedo são uma causa comum de tarefas que falham alguns minutos após o envio.
  • Mantenha o vídeo curto e com imagem estável. Material de referência longo, com tremor intenso ou cortes frequentes fornece ao modelo um sinal de movimento ambíguo.

Se o material estiver em armazenamento privado, gere a URL assinada no momento do envio, com validade suficientemente longa, e não no momento do upload.

Parâmetros de movimento e saída

Parâmetros normalmente definidos junto com o vídeo de referência:

  • O prompt de texto que descreve o conteúdo-alvo, a ser conduzido pelo movimento de referência.
  • Configurações de proporção e duração da saída, para que o vídeo gerado se ajuste ao seu local de exibição.
  • Quaisquer configurações de intensidade ou fidelidade de movimento expostas pelo modelo, para equilibrar a fidelidade à referência e a liberdade do prompt.

Reúna esses parâmetros em um objeto de configuração pequeno e explícito no cliente, em vez de espalhá-los por parâmetros de função. Isso facilita registrar com precisão o que foi enviado, que é o material de depuração mais útil para esse modelo.

Por fim, valide antes de enviar: a URL de referência retorna um content-type de mídia, o prompt não está vazio e todas as configurações numéricas estão dentro dos intervalos documentados. A verificação local leva milissegundos; uma tarefa assíncrona rejeitada custa uma ida e volta e confusão.

Tarefa assíncrona: enviar, consultar e ler o resultado

O controle de movimento não retorna o vídeo na resposta de envio, mas sim uma tarefa que você precisa acompanhar. Construa o cliente em torno desse ciclo de vida desde o início.

Passo 1 — Envio

Faça um POST da tarefa no endpoint do modelo. Um envio bem-sucedido retorna um identificador de tarefa. Persista esse ID imediatamente — é o único handle para operar a tarefa, usado tanto na consulta quanto em solicitações de suporte.

Passo 2 — Consulta

Faça um GET do status da tarefa com esse ID. O campo de status indica uma de três situações:

  • Pendente ou na fila: aceita, ainda não iniciada. Continue aguardando.
  • Processando ou em execução: em andamento. Continue aguardando, mas com backoff.
  • Estado terminal: sucesso ou falha. Pare de consultar.

O loop de consulta deve verificar explicitamente os estados terminais, e não apenas se o campo de saída existe. Tarefas com falha não têm resultado, e tratar “ainda sem resultado” como “ainda em execução” leva a um loop infinito.

Passo 3 — Ler o resultado

Em caso de sucesso, a resposta traz a localização da saída, normalmente a URL do vídeo gerado. Baixe-a prontamente para o seu próprio armazenamento — um ativo gerado por trás de uma URL temporária não deve ser considerado permanentemente disponível.

Boas práticas de consulta

Duas regras mantêm isso confiável em produção:

  1. Faça backoff entre as consultas (comece com um ou dois segundos e aumente), em vez de martelar o endpoint.
  2. Limite o tempo total de espera e exponha o timeout como um erro repetível, em vez de bloquear a thread de trabalho para sempre.

Registre, para cada execução, o ID da tarefa, os parâmetros enviados e o estado final. Quando algo der errado, esse log responde à maior parte das perguntas antes de você precisar perguntar a alguém.

Requisição curl executável

Abaixo está o fluxo completo no shell. Ele envia a tarefa, extrai o ID da tarefa e então consulta até a tarefa entrar em estado terminal.

#!/usr/bin/env bash
set -euo pipefail

BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"

# 1) enviar a tarefa
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "prompt": "um barco de papel flutuando por uma rua urbana na chuva, com estética cinematográfica",
    "reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
    "duration": 5,
    "aspect_ratio": "16:9"
  }')

echo "$SUBMIT"

TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"

# 2) consultar até o estado terminal
while true; do
  STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
  echo "status: $STATUS"

  case "$STATUS" in
    succeeded) echo "$STATUS_JSON"; break ;;
    failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
  esac

  sleep 3
done

Duas observações sobre a adaptação deste script. Primeiro, mantenha o identificador do modelo e o caminho do endpoint em variáveis para que o script continue legível. Segundo, a análise acima não usa jq, apenas Python, porque Python está disponível em quase todos os lugares; se preferir jq, pode substituir. De qualquer forma, o comportamento essencial é o mesmo: extrair o ID da tarefa da resposta de envio e então consultar seu status até ver um valor de estado terminal.

A mesma requisição (versão Python)

O cliente Python abaixo corresponde ao fluxo curl, mas com um loop de consulta mais robusto: backoff aproximadamente exponencial, timeout total e tratamento explícito de cada estado terminal.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"

HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

TERMINAL = {"succeeded", "failed", "cancelled"}


def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "reference_video_url": reference_video_url,
        "duration": duration,
        "aspect_ratio": "16:9",
    }
    r = requests.post(
        f"{BASE}/v1/videos/generations",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["id"]


def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/videos/generations/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in TERMINAL:
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = submit_job(
        prompt="um barco de papel flutuando por uma rua urbana na chuva, com estética cinematográfica",
        reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
    )
    print("submitted:", task_id)
    result = wait_for_job(task_id)

    if result["status"] == "succeeded":
        print("output:", result.get("output"))
    else:
        print("job did not succeed:", result)

Pontos que vale a pena manter ao adaptar: o conjunto de estados terminais, o backoff com limite superior e as funções separadas de envio e espera. Em um serviço real, você as dividiria em dois processos — enviar a partir do handler de requisição, armazenar o ID da tarefa e deixar um worker consultar — para que tarefas lentas nunca bloqueiem a resposta HTTP.

Pontos comuns de falha e como depurá-los

A maioria dos problemas de integração com o kling-3.0/motion-control se enquadra em poucas categorias. Verifique na ordem.

Erros de autenticação e de modelo

401 quase sempre significa que o bearer token está ausente, truncado ou veio do ambiente errado. Um erro de modelo não encontrado significa que a string de model não corresponde exatamente — é um identificador separado por barra, então ordem de caracteres errada ou espaços extras falham silenciosamente na configuração e explicitamente na API.

Vídeo de referência indisponível

A tarefa é aceita e, minutos depois, falha porque não conseguiu buscar a URL de referência. Causas em ordem de frequência: a URL assinada expirou antes do processamento; a URL exige um cabeçalho de autenticação que o serviço não envia; a URL retorna HTML (página de login ou de erro) em vez de vídeo. Teste a URL de fora da sua rede com um curl comum e confirme o content-type.

Formato de parâmetro inválido ou fora do intervalo

Configurações de duração e proporção fora dos intervalos documentados são rejeitadas no envio, o que é bom — você recebe o erro imediatamente. Valide localmente primeiro, para que erros de digitação não exijam uma ida e volta para serem descobertos.

Falhas de consulta

Dois problemas clássicos: o loop verifica apenas o campo de saída e nunca failed, causando um loop infinito; e a consulta em loop apertado e sem pausa faz você ser limitado por rate limit. Adicione verificação explícita de estado terminal e backoff, e sempre inclua o ID da tarefa nos relatórios de erro, para consultar a tarefa em vez de recriá-la.

URL do resultado expirada

Você gerou o vídeo, mas salvou apenas a URL de saída temporária. Baixe a saída para o seu próprio armazenamento imediatamente após o sucesso da tarefa; trate a URL retornada como um handle de download, não como armazenamento persistente.

Inicie cada sessão de depuração registrando o corpo exato da requisição e o JSON bruto da resposta. Quase todos os problemas acima podem ser vistos nesses dois materiais. Quando estiver pronto para se aprofundar, consulte a documentação do HiAPI.ai para outros modelos de vídeo e a referência de endpoints, e mantenha a mesma forma de cliente “envie primeiro, consulte depois”.

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