API Wan 2.7 VideoEdit na Novita AI: Como Editar Vídeos com IA

Wan 2.7 VideoEdit na Novita AI é o endpoint certo quando você já tem um vídeo e deseja que o modelo reestilize ou reescreva a cena sem reconstruir o movimento do zero. Você envia um vídeo de origem para POST https://api.novita.ai/v3/async/wan2.7-videoedit, recebe um task_id e então faz polling em GET /v3/async/task-result até que o clipe editado esteja pronto. Este guia mostra a estrutura exata da requisição, quando adicionar imagens de referência e os detalhes de implementação que importam antes de integrar em produção.

Quando o Wan 2.7 VideoEdit é a Ferramenta Certa

Use o Wan 2.7 VideoEdit quando o timing e o movimento de câmera no seu clipe de origem já são bons o suficiente e você quer que a IA mude o que o espectador vê, em vez de como a cena é enquadrada.

Aplicações típicas:

• Você tem um clipe live-action e quer convertê-lo em um render anime, cinematográfico ou estilizado.
• Você precisa mudar figurino, ambiente, adereços ou atmosfera preservando o arco de movimento original.
• Você quer aplicar uma transformação guiada por prompt ao vídeo e, opcionalmente, ancorar a aparência com uma imagem de referência.

Não é o endpoint certo quando:

• Você precisa de movimento novo a partir apenas de texto. Use Wan 2.7 T2V.
• Você quer animar uma imagem estática. Use Wan 2.7 I2V.
• Você precisa de role-play com múltiplos personagens com slots de referência nomeados em uma cena gerada. Use Wan 2.7 R2V.

Essa distinção é importante porque o VideoEdit começa a partir de um clipe de entrada. Se o movimento original estiver errado, o modelo não corrigirá a coreografia para você.

Endpoint e Fluxo de Trabalho Verificados

O Wan 2.7 VideoEdit na Novita AI usa um endpoint de submissão e o endpoint compartilhado de resultado de tarefa assíncrona:

Campo	Valor
Endpoint de submissão	POST https://api.novita.ai/v3/async/wan2.7-videoedit
Polling de resultado	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Cabeçalho de autenticação	Authorization: Bearer $NOVITA_API_KEY
Tipo de conteúdo	application/json
Documentação oficial	Referência da API Wan 2.7 VideoEdit

A API é assíncrona. Uma chamada de submissão bem-sucedida retorna um task_id, não a URL do vídeo finalizado. Sua aplicação deve persistir esse ID de tarefa e construir lógica de polling ou de tarefa em segundo plano em torno dele.

Passo 1: Obter uma Chave de API da Novita AI

Crie uma chave em Gerenciamento de chaves da Novita AI e mantenha-a em uma variável de ambiente:

export NOVITA_API_KEY="sua_chave_api_aqui"

Não codifique a chave diretamente em código de navegador, aplicativos móveis ou arquivos de configuração versionados.

Passo 2: Entender a Estrutura da Requisição

O Wan 2.7 VideoEdit usa um corpo JSON simples. A requisição não aninha campos sob input ou parameters.

No mínimo, envie:

• video_url
• prompt

Os campos opcionais documentados com os quais você geralmente se importará primeiro são:

• reference_image_url para uma referência de aparência/estilo
• resolution
• duration
• audio_setting
• prompt_extend
• seed

Passo 3: Enviar Sua Primeira Requisição VideoEdit

Esta é a requisição prática mínima:

curl -s -X POST https://api.novita.ai/v3/async/wan2.7-videoedit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/source-clip.mp4",
    "prompt": "Transforme esta cena de corredor de escritório em um corredor cyberpunk neon, preserve o movimento de caminhada e o trajeto da câmera",
    "resolution": "720P",
    "duration": 5
  }'

Resposta esperada:

{
  "task_id": "abc123..."
}

Nada mais é garantido no momento da submissão. Trate a requisição como uma etapa de enfileiramento de trabalho, não como uma resposta de edição síncrona.

Passo 4: Fazer Polling no Endpoint de Resultado da Tarefa

Use o task_id retornado com a API compartilhada de resultado de tarefa:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Construa em torno destes estados:

Status	Significado
TASK_STATUS_QUEUED	Aceito e aguardando execução
TASK_STATUS_PROCESSING	A edição está em andamento
TASK_STATUS_SUCCEED	O vídeo editado está pronto
TASK_STATUS_FAILED	A tarefa falhou; inspecione o corpo da resposta

Quando a tarefa for bem-sucedida, a resposta inclui um array videos com a URL do vídeo editado e o TTL da URL. Baixe ou mova esse ativo prontamente, em vez de tratar a URL hospedada como armazenamento permanente.

Passo 5: Adicionar uma Imagem de Referência Quando Precisar de Controle Visual Mais Apertado

reference_image_url é opcional, mas altera o comportamento da edição de maneiras úteis.

Use quando:

• Você quer que o clipe final siga uma aparência, figurino ou paleta de personagem específica.
• Você quer direcionar a saída para uma direção artística específica, em vez de deixar tudo para o prompt de texto.
• O movimento do vídeo de origem está correto, mas a identidade da cena está muito solta com orientação apenas por texto.

Exemplo de requisição com imagem de referência:

curl -s -X POST https://api.novita.ai/v3/async/wan2.7-videoedit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/source-clip.mp4",
    "reference_image_url": "https://example.com/reference-look.png",
    "prompt": "Transforme o performer na aparência e paleta de cores da imagem de referência, mantendo o mesmo timing de dança",
    "resolution": "1080P",
    "duration": 6,
    "audio_setting": "auto"
  }'

Se o resultado continuar desviando, a correção usual não é um prompt mais longo. É um prompt mais preciso combinado com uma imagem de referência melhor.

Parâmetros Chave com os Quais Você Realmente Deve se Importar

Parâmetro	Tipo	Obrigatório	O que faz
video_url	string	Sim	Vídeo de origem a ser editado
prompt	string	Sim	Descreve a transformação alvo
reference_image_url	string	Não	Imagem de referência para ancoragem de aparência e estilo
resolution	string	Não	Resolução de saída; valores documentados incluem 720P e 1080P
duration	integer	Não	Duração alvo da saída em segundos; 0 mantém a duração completa do vídeo de entrada
audio_setting	string	Não	Controla o comportamento de geração de áudio
prompt_extend	boolean	Não	Permite que o modelo expanda prompts curtos automaticamente
seed	integer	Não	Melhora a reprodutibilidade entre tentativas

Consulte a referência oficial de parâmetros antes de assumir valores padrão. Os campos de modelos de vídeo mudam com mais frequência do que os de modelos de texto, e é fácil errar nas restrições de saída se você confiar na memória.

Limites Documentados e Restrições Práticas

Em 29 de julho de 2026, a documentação oficial da Novita para Wan 2.7 VideoEdit documenta estes limites:

• Resoluções suportadas: 720P e 1080P
• duration padrão é 0, o que significa a duração completa do vídeo de entrada; a faixa de duração explícita documentada para saída é de 2 a 10 segundos quando você a define
• Formatos de vídeo de entrada: mp4 e mov
• Limite de tamanho do vídeo de entrada: até 100 MB
• Formatos de imagem de referência: jpg, jpeg, png, webp
• Limite de tamanho da imagem de referência: até 20 MB
• Formato de vídeo de saída: mp4

Essas restrições são fáceis de ignorar ao construir um pipeline de mídia genérico. A falha de integração mais comum é enviar um arquivo de origem mais longo ou maior do que o endpoint aceita.

Duas implicações práticas:

1. Se você quiser que o clipe editado preserve a duração da origem, omita duration ou defina-o como 0 em vez de forçar um corte de 2 a 10 segundos.
2. Se você estiver testando prompts rapidamente, use 720P primeiro e mude para 1080P somente quando a transformação estiver funcionando.

Exemplo em Python: Submeter e Fazer Polling

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_video_edit(
    video_url: str,
    prompt: str,
    reference_image_url: str | None = None,
    resolution: str = "720P",
    duration: int = 0,
    audio_setting: str = "auto",
    prompt_extend: bool = True,
    seed: int | None = None,
) -> str:
    payload = {
        "video_url": video_url,
        "prompt": prompt,
        "resolution": resolution,
        "duration": duration,
        "audio_setting": audio_setting,
        "prompt_extend": prompt_extend,
    }
    if reference_image_url:
        payload["reference_image_url"] = reference_image_url
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        f"{BASE_URL}/v3/async/wan2.7-videoedit",
        headers=HEADERS,
        json=payload,
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            headers=HEADERS,
            params={"task_id": task_id},
            timeout=60,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")

        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            reason = data.get("task", {}).get("reason", "unknown")
            raise RuntimeError(f"Tarefa {task_id} falhou: {reason}")

        time.sleep(interval)

    raise TimeoutError(f"Tarefa {task_id} não foi concluída em {timeout}s")


if __name__ == "__main__":
    task_id = submit_video_edit(
        video_url="https://example.com/source-clip.mp4",
        prompt="Mude a cena de rua para uma cidade retro-futurista chuvosa à noite, preserve o plano-sequência original",
        reference_image_url="https://example.com/reference-frame.png",
        resolution="720P",
        duration=0,
        seed=42,
    )
    print(f"Tarefa submetida: {task_id}")

    result = poll_result(task_id)
    video = result["videos"][0]
    print("URL do vídeo editado:", video["video_url"])
    print("TTL da URL:", video["video_url_ttl"])

Exemplo em cURL com Polling via Shell

TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/wan2.7-videoedit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/source-clip.mp4",
    "prompt": "Converta o clipe em uma cena de cidade anime desenhada à mão, preserve o movimento de corrida",
    "resolution": "720P",
    "duration": 0,
    "prompt_extend": true
  }' | jq -r '.task_id')

while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task.status')

  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.videos[0].video_url'
    break
  fi

  if [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "$RESULT"
    break
  fi

  sleep 5
done

Se você estiver integrando a partir de um serviço backend, envolva este loop de polling em um worker em vez de manter uma requisição de usuário aberta durante toda a janela de geração.

Preços, Créditos e o Que Verificar Antes de Estimar Custos

A Novita AI expõe preços para modelos de vídeo em suas páginas de modelo e preços, mas esses números podem mudar. Para Wan 2.7 VideoEdit, verifique as taxas atuais diretamente na página de preços da Novita AI e na entrada do modelo vinculada na documentação oficial antes de publicar estimativas de custo voltadas ao cliente.

Para planejamento de engenharia, a suposição mais segura é:

• O custo escala com as configurações do clipe gerado, não apenas com uma taxa fixa por requisição.
• Execuções em 1080P são a linha de base errada para iteração.
• Clipes mais curtos são mais fáceis de validar e mais baratos de depurar.

Se você estiver construindo ferramentas internas, trate a consulta de preços como uma preocupação de configuração, não como uma constante embutida no código.

Erros Comuns de Integração

Enviar uploads brutos em vez de uma URL acessível. A estrutura de requisição documentada espera entradas de mídia baseadas em URL. Certifique-se de que seu clipe de origem já esteja disponível em uma URL estável que seu servidor possa referenciar.

Usar VideoEdit para mudanças de movimento. VideoEdit é um endpoint de transformação, não um endpoint de coreografia. Se o movimento original estiver errado, regenere com T2V ou I2V.

Confundir os limites de vídeo de origem e imagem de referência. O vídeo de origem é o ativo maior: mp4/mov, até 100 MB. O limite menor de 20 MB se aplica a reference_image_url, não a video_url.

Fazer polling muito agressivamente. Acessar o endpoint de resultado da tarefa a cada segundo é desnecessário para trabalhos de vídeo de vários segundos. Um intervalo de 5 a 10 segundos geralmente é um ponto de partida melhor.

Ignorar o TTL da URL. A URL do resultado é temporária. Persista o ativo prontamente se o clipe editado for importante para etapas posteriores.

Pular a especificidade do prompt. “Melhore” não é um prompt de edição. Descreva o estilo alvo, ambiente, tratamento do assunto e qual movimento deve permanecer inalterado.

Qual Endpoint Wan 2.7 Você Deve Escolher?

Use esta regra rápida:

• Escolha VideoEdit quando você já tem um vídeo de origem.
• Escolha I2V quando você tem uma imagem de origem ou deseja continuação a partir de um fluxo de trabalho baseado em imagem estática.
• Escolha T2V quando você tem apenas texto.
• Escolha R2V quando a consistência de identidade e o controle de personagem de referência são mais importantes do que editar um clipe existente.

Essa separação é o que mantém sua integração simples. As equipes geralmente usam excessivamente texto-para-vídeo para tarefas que são, na verdade, problemas de edição baseados em prompt.

FAQ

Qual é o endpoint da Novita AI para Wan 2.7 VideoEdit?

POST https://api.novita.ai/v3/async/wan2.7-videoedit. Ele retorna um task_id, então você faz polling em GET https://api.novita.ai/v3/async/task-result?task_id=<id> para conclusão.

Posso fornecer uma imagem de referência junto com o vídeo de origem?

Sim. A estrutura de requisição documentada suporta um reference_image_url opcional junto com video_url e prompt, o que é útil para direcionar a aparência final de forma mais precisa.

Qual duração de vídeo o Wan 2.7 VideoEdit suporta na Novita AI?

Conforme documentado em 29 de julho de 2026, duration padrão é 0, o que significa a duração completa do vídeo de entrada. Se você definir duration explicitamente, a faixa documentada é de 2 a 10 segundos.

O Wan 2.7 VideoEdit aceita vídeos de origem grandes?

Sim, dentro do limite documentado. A documentação oficial lista entrada mp4/mov de até 100 MB. O limite separado de 20 MB se aplica à imagem de referência opcional.

Devo usar Wan 2.7 VideoEdit ou Wan 2.7 I2V?

Use VideoEdit se você já tem um clipe e deseja transformá-lo. Use I2V se seu ponto de partida é uma imagem estática ou um fluxo de trabalho baseado em imagem.

Artigos recomendados

• Wan 2.7 na Novita AI: Texto-para-Vídeo vs Imagem-para-Vídeo vs Referência-para-Vídeo
• Kling O1 na Novita AI: Modos T2V, I2V, Ref2V e Edição de Vídeo
• Início Rápido PixVerse V4.5 para Geração de Texto-para-Vídeo e Imagem-para-Vídeo