Início Rápido da API Kling V3.0 Motion Control

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 aborda 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 Certa

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 Image-to-Video (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 uma 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 em diferentes personagens (mesmo vídeo de referência, imagens diferentes)
• Você está criando conteúdo onde a qualidade do movimento é importante e os resultados abertos do I2V com prompt são imprevisíveis demais

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

Passo 1: Obtenha Sua Chave de API da 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 se comprometer com o volume de produção.

Passo 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_DE_API_NOVITA
Content-Type: application/json

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

Passo 3: Prepare Suas Entradas

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

Imagem de Referência

Este é o personagem cuja aparência será preservada na saída. Requisitos:

• Formatos: JPEG, PNG, JPG
• Tamanho máximo: 10 MB
• Resolução mínima: 340px em cada lado
• Proporção de aspecto: entre 2:5 e 5:2
• O personagem deve estar claramente visível, ocupar mais de 5% da área 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 corporais 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 do 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: 340px em cada lado
• Proporção de aspecto: entre 2:5 e 5:2
• A pessoa no vídeo de referência deve ter o corpo inteiro ou parte superior visível e desobstruída, incluindo a cabeça

Gravações claras e bem iluminadas com fundo mínimo transferem o movimento com mais precisão do que takes ruidosos ou cheios.

Passo 4: Envie Sua Primeira Requisição

Requisiçã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"
}

Passo 5: Consulte o Resultado

O Kling V3.0 Motion Control é assíncrono. Envie a tarefa e 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ído, 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–10 segundos em vez de sobrecarregar o endpoint.

Exemplo Completo de Integração em Python

Este script envia uma tarefa de Motion Control e consulta até que seja concluída:

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 seu vídeo de referência mostra um dançarino de frente e a imagem do seu personagem também está de frente, "video" dará uma 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 indesejadas de perspectiva — mas note que gera um clipe fixo de 5 segundos.

Standard vs. Pro: Qual Nível de Qualidade Escolher

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

Standard 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 aprimorada e consistência do sujeito. 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 nas roupas 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 Standard 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 Standard 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

A tarefa falha imediatamente com um erro 422 ou de validação Verifique se ambas as URLs image e video são acessíveis publicamente (não atrás de autenticação ou de 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 da tarefa.

O movimento de saída parece estranho ou o personagem se 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.

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

O movimento do vídeo de referência não é transferido corretamente Gravações de referência ruidosas ou cheias degradam a extração de movimento. Use gravações onde o performer seja o sujeito principal contra um fundo razoavelmente limpo. Evite gravações instáveis feitas à mão se o objetivo for uma transferência de movimento suave.

Status preso em processing por mais de 3 minutos Atrasos ocasionais na 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 Criam com o Kling Motion Control

Animação de personagens para assets de jogos: Pegue uma ilustração de personagem e aplique um clipe de movimento de referência (andar, correr, atacar) sem rigging ou software de 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 se parece em um design de personagem antes de investir na produção de animação completa.

Exibição de produtos em 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 que mostre o movimento das vestimentas.

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 principal: 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 a 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 é melhor transferido a partir 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 Standard ou Pro. Consulte a cada 8–10 segundos, em vez de um loop intenso.

Artigos Recomendados

• Kling O1 na Novita AI: Modos T2V, I2V, Ref2V e Edição de Vídeo
• Kling 3.0 Agora na Novita AI: Geração de Vídeo Cinematográfico com IA em Escala
• API Kling V2.5 Turbo na Novita AI