Tutorial
Como usar o kling-3.0/motion-control com a API HiAPI: exemplos em curl e Python
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:
- Faça backoff entre as consultas (comece com um ou dois segundos e aumente), em vez de martelar o endpoint.
- 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 →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio