Início Rápido da API de Controle de Movimento Kling V3.0

O Kling V3.0 Motion Control permite animar uma imagem de personagem estática extraindo o movimento de um vídeo de referência e aplicando-o quadro a quadro. A saída preserva a aparência do personagem da sua imagem enquanto reproduz o movimento do vídeo — uma técnica chamada transferência de movimento. Este guia cobre o endpoint da Novita AI, entradas necessárias, parâmetros principais e exemplos funcionais em Python e curl que você pode executar com uma chave de API real.

Quando o Motion Control é a Ferramenta Adequada

O Motion Control é a ferramenta certa quando você tem duas coisas: uma imagem de personagem estática que deseja animar e um vídeo de referência cujo movimento deseja reproduzir. É diferente de Imagem-para-Vídeo (I2V), que gera movimento a partir de um prompt. Com o Motion Control, o movimento é copiado do vídeo de referência com precisão — o personagem de saída seguirá o mesmo arco de movimento que a pessoa no vídeo de referência.

Use quando:

• Você deseja um passo de dança, ciclo de caminhada ou gesto específico aplicado a uma ilustração ou foto de personagem
• Você precisa de movimento consistente e reproduzível entre diferentes personagens (mesmo vídeo de referência, imagens diferentes)
• Você está criando conteúdo onde a qualidade do movimento importa e os resultados abertos de prompts I2V são muito imprevisíveis

Não use quando o movimento em si ainda está indefinido — nesse caso, o I2V com um prompt descritivo oferece mais flexibilidade com menor custo.

Etapa 1: Obtenha Sua Chave de API Novita

Cadastre-se em novita.ai e gere uma chave de API no painel. Novas contas recebem créditos gratuitos que você pode usar para testar o Motion Control antes de comprometer o volume de produção.

Etapa 2: Confirme o Endpoint e o ID do Modelo

O Kling V3.0 Motion Control na Novita AI usa o padrão de vídeo assíncrono:

Enviar tarefa:

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

Consultar resultado:

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

Todas as requisições exigem:

Authorization: Bearer SUA_CHAVE_NOVITA_API
Content-Type: application/json

Documentação completa: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

Etapa 3: Prepare Suas Entradas

O Motion Control exige duas entradas: uma imagem de referência e um vídeo de referência. Acertar isso é o maior fator na qualidade da saída.

Imagem de Referência

Este é o personagem cuja aparência a saída preservará. Requisitos:

• Formatos: JPEG, PNG, JPG
• Tamanho máximo: 10 MB
• Resolução mínima: 340 px em cada lado
• Proporção de trov: entre 2:5 e 5:2
• O personagem deve estar claramente visível, ocuar mais de 5% da ára da imagem e não ter oclusão pesada (não corte a cabeça ou o corpo)

Para melhores resultados, use uma imagem onde as proporções do corpo do personagem correspondam aproximadamente ao que está visível no vídeo de referência. Se o vídeo de referência mostra um dançarino de corpo inteiro, use uma imagem de personagem de corpo inteiro em vez de um recorte de retrato.

Vídeo de Referência

Esta é a fonte de movimento. O personagem na saída replicará os movimentos deste vídeo:

• Formatos: MP4, MOV
• Tamanho máximo: 10 MB
• Duração: 3–30 segundos
• Resolução mínima: 340 px em cada lado
• Proporção de trov: entre 2:5 e 5:2
• A pessoa no vídeo de referência deve ter o corpo inteiro ou a parte superior visível e desobstruída, incluindo a cabeça

Gravações claras e bem iluminadas com fundo limpo transferem movimento com mais precisão do que tomadas ruidosas ou com muitas pessoas.

Etapa 4: Envie Sua Primeira Solicitação

Solicitação curl mínima:

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "A person performing a smooth dance routine, cinematic lighting",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

A resposta retorna um task_id imediatamente:

{
  "task_id": "abc123xyz"
}

Etapa 5: Consulte o Resultado

O Kling V3.0 Motion Control é assíncrono. Envie a tarefa, depois consulte até que o status seja succeed:

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

Quando concluída, a resposta contém um array videos com a URL de saída:

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

O tempo típico de geração é de 30 a 120 segundos, dependendo da duração do vídeo e do modo. Consulte a cada 5 a 10 segundos, sem sobrecarregar o endpoint.

Exemplo Completo de Integração Python

Este script envia uma tarefa de motion control e consulta até completar:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

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

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(8)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("Submitting task...")
    task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
    print(f"Task ID: {task_id}")

    print("Polling for result...")
    output_url = poll_result(task_id)
    print(f"Output video: {output_url}")

Referência de Parâmetros da API

Parâmetro	Tipo	Obrigatório	Descrição
image	string	Sim	URL da imagem do personagem a ser animada. Veja os requisitos de entrada acima.
video	string	Sim	URL do vídeo de referência cujo movimento será transferido.
model_name	string	Sim	Defina como kling-v3.0-motion-control.
prompt	string	Não	Descrição textual do estilo de movimento desejado ou contexto da cena. Opcional, mas pode melhorar a qualidade da saída.
character_orientation	string	Não	Controla o alinhamento da pose e a duração da saída. "video" corresponde à orientação do vídeo de referência — melhor para movimentos complexos de corpo inteiro, suporta até 30s. "image" corresponde à orientação da imagem do personagem — melhor para movimentos relativos à câmera, fixo em 5s.

character_orientation na prática

Se o vídeo de referência mostra um dançarino de frente e sua imagem de personagem também está de frente, "video" dará melhor transferência de movimento e suporta até 30 segundos. Se o vídeo de referência tem uma câmera que se move ao redor do sujeito e sua imagem é um retrato de ângulo fixo, "image" tende a reduzir distorções de perspectiva indesejadas — mas note que gera um clipe fixo de 5 segundos.

Padrão vs. Pro: Qual Nível de Qualidade Escolher

O Kling V3.0 Motion Control está disponível em dois níveis de qualidade:

Padrão gera saída em 720p. É a escolha certa para iteração, teste de compatibilidade de movimento ou geração de rascunhos antes de se comprometer com uma versão final.

Pro gera saída em 1080p com fidelidade de movimento e consistência de assunto melhoradas. Use Pro quando:

• A saída vai para uma produção finalizada (postagem em redes sociais, curta-metragem, demonstração de produto)
• Detalhes finos no rosto ou na roupa do personagem são importantes
• Você está gerando clipes mais longos (10s+) onde a degradação da qualidade ao longo do tempo é mais visível

Para a maioria dos fluxos de trabalho de desenvolvimento, comece com Padrão para confirmar a compatibilidade das entradas e a qualidade do movimento, depois mude para Pro para a versão final.

Preços, Duração e Estimativas de Custo

A Novita AI cobra o Motion Control por segundo de vídeo gerado. Os níveis Padrão e Pro têm taxas por segundo separadas. Para preços atuais, consulte a página do modelo Novita AI.

Limites de duração:

• character_orientation: "video" — até 30 segundos
• character_orientation: "image" — fixo em 5 segundos

O custo escala com a duração para o modo "video". O modo "image" sempre gera um clipe de 5 segundos.

Solução de Problemas Comuns

Tarefa falha imediatamente com erro 422 ou de validação Verifique se tanto image quanto video são URLs publicamente acessíveis (não atrás de autenticação ou uma URL pré-assinada de curta duração que expirou). O backend da Novita deve conseguir buscar ambos os arquivos no momento da execução.

Movimento de saída parece errado ou o personagem distorce A causa mais comum é uma incompatibilidade entre a orientação do personagem na imagem e no vídeo de referência. Tente alternar character_orientation entre "video" e "image" para ver qual produz melhor alinhamento.

Personagem perde a identidade facial no meio do clipe Certifique-se de que o personagem na imagem de referência tenha rosto e corpo claros e desobstruídos. Para clipes mais longos, o nível Pro mantém a consistência do assunto melhor que o Padrão.

Movimento do vídeo de referência não transfere de forma limpa Gravações de referência ruidosas ou com muita gente degradam a extração de movimento. Use gravações onde o performer seja o sujeito principal contra um fundo razoavelmente limpo. Evite gravações tremidas de mão se o objetivo for transferência suave de movimento.

Status preso em processing por mais de 3 minutos Atrasos ocasionais de fila acontecem. Aguarde até 5 minutos antes de considerar como travado. Se permanecer travado, envie uma nova tarefa — não reutilize o task_id antigo.

O que os Desenvolvedores Constroem com o Kling Motion Control

Animação de personagens para ativos de jogos: Pegue uma ilustração de personagem e aplique um clipe de movimento de referência (caminhada, corrida, ataque) sem software de rigging ou animação.

Conteúdo social com movimento consistente: Aplique o mesmo vídeo de dança de referência a várias imagens de personagens para produzir uma série de clipes com coreografia idêntica, mas aparências diferentes.

Pré-visualização: Teste como uma sequência de movimento específica fica no design de um personagem antes de investir em animação de produção completa.

Exibição de produtos de e-commerce: Aplique mudanças sutis de pose ou movimento de roupas em imagens de produtos usando um vídeo de referência cuidadosamente escolhido mostrando movimento de vestuário.

FAQ

Qual é a diferença entre Motion Control e Image-to-Video na Novita AI?

Image-to-Video (I2V) anima uma imagem com base em um prompt de texto — o movimento é gerado pelo modelo a partir da sua descrição. O Motion Control transfere movimento específico de um vídeo de referência para o personagem na sua imagem. O Motion Control oferece movimento preciso e reproduzível; o I2V oferece flexibilidade criativa sem precisar de um clipe de referência.

O personagem do vídeo de referência precisa corresponder à aparência do personagem da imagem?

Não. O vídeo de referência é usado apenas para extração de movimento — o personagem de saída vem da imagem, não do vídeo. Essa é a capacidade central: movimento de uma fonte, aparência de outra. As proporções devem corresponder aproximadamente (imagem de corpo inteiro para vídeo de corpo inteiro, retrato para vídeo de parte superior) para melhor qualidade de transferência.

Posso usar qualquer vídeo disponível publicamente como referência?

Você pode usar qualquer vídeo que atenda aos requisitos de formato e tamanho. O movimento é transferido melhor de gravações onde o sujeito está claramente visível com oclusão mínima. Cenas complexas com várias pessoas ou gravações fortemente editadas (cortes, zooms) podem reduzir a precisão.

Quanto tempo leva a geração?

Normalmente de 30 a 120 segundos, dependendo da duração da saída e se você escolheu o modo Padrão ou Pro. Consulte a cada 8–10 segundos, não em um loop apertado.

Artigos Recomendados

• Kling 3.0 Agora na Novita AI: Geração de Vídeo AI Cinematográfica em Escala
• Início Rápido da API Kling V3.0 4K
• API Kling V2.5 Turbo na Novita AI