Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Edição de vídeo com /v1/videos/edits

Aula 7 de 12 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. Editar um vídeo existente
  2. O endpoint POST /v1/videos/edits
  3. O que pedir numa edição
  4. O ciclo assíncrono, idêntico à geração
  5. Defina o que muda e o que permanece
  6. Pontos-chave

Atualizado em 3 de novembro de 2026. Com base na página Video Editing da xAI: o vídeo de origem tem no máximo 8,7 segundos de duração; o resultado mantém a duração, a proporção e a resolução (máximo de 720p); e a extensão utiliza o mesmo objeto video que a edição. A afirmação anterior de que a edição era pouco fiável para elementos específicos contradiz os exemplos da xAI, que se focam precisamente em edições precisas. Fontes: Video Editing · Video Overview.

Editar um vídeo existente

A geração é apenas parte do trabalho. A API da xAI também disponibiliza um endpoint de edição de vídeo que recebe uma sequência existente e a modifica com base em instruções de texto. É o equivalente em vídeo à edição de imagem, mas com restrições de formato mais rigorosas. Antes de escrever o seu primeiro pedido, tome nota dos quatro limites que determinam o que pode submeter.

8.7 s
Duração máxima da origem
720p
Resolução máxima
H.265
Codec aceite (como H.264, AV1)
MP4
Formato obrigatório

O endpoint POST /v1/videos/edits

O pedido associa um vídeo de origem a uma instrução que descreve a modificação desejada.

{
  "model": "grok-imagine-video",
  "prompt": "Change the background to a sunset over the ocean",
  "video": {
    "url": "https://example.com/original-video.mp4"
  }
}

Três campos são suficientes: model, que permanece grok-imagine-video; prompt, que contém a descrição da modificação; e video.url, que aponta para o ficheiro MP4 a processar. Note que o vídeo está encapsulado num objeto video, que aceita um url ou o file_id de um ficheiro carregado: o endpoint de extensão, na próxima lição, adota a mesma convenção.

As restrições técnicas são aqui mais rigorosas do que na geração. A origem não pode exceder 8,7 segundos e o vídeo produzido mantém essa duração; a página Video Generation menciona uma duração “limitada a 8,7 segundos” sem detalhar o tratamento de uma origem mais longa: por isso, corte as suas origens antecipadamente. A resolução limita-se a 720p. O ficheiro de entrada deve ser um MP4 num codec suportado, como H.264, H.265 ou AV1. O ponto mais confuso para quem vem da geração: não tem controlo sobre a duração, a proporção ou a resolução do resultado, pois tudo é determinado pelo vídeo de origem. O pedido de edição não inclui nenhum campo duration, aspect_ratio ou resolution.

O que pedir numa edição

A substituição de fundo é o caso clássico: o sujeito mantém-se, o cenário muda.

{
  "model": "grok-imagine-video",
  "prompt": "Replace the background with a space landscape with stars and nebulae. Keep the same subject and the same movement.",
  "video": {"url": "https://example.com/video.mp4"}
}

As alterações de estilo afetam toda a imagem e transformam o estilo do clipe sem modificar a sua ação — prático para adaptar a mesma sequência a diferentes universos.

{
  "model": "grok-imagine-video",
  "prompt": "Transform this video into a Japanese cartoon style with vivid colors",
  "video": {"url": "https://example.com/video.mp4"}
}

Adicionar elementos enriquece a cena com camadas que não existiam durante as filmagens, geralmente atmosféricas.

{
  "model": "grok-imagine-video",
  "prompt": "Add falling snow and a frost effect on the edges",
  "video": {"url": "https://example.com/video.mp4"}
}

Por fim, a modificação da iluminação equivale a uma correção de cor da sequência: as mesmas tomadas, uma atmosfera radicalmente diferente.

{
  "model": "grok-imagine-video",
  "prompt": "Change the lighting to a night ambiance with blue and purple neon lights",
  "video": {"url": "https://example.com/video.mp4"}
}

O ciclo assíncrono, idêntico à geração

A edição segue exatamente o mesmo protocolo de quatro passos que a geração: envia o pedido, recebe um request_id, consulta GET /v1/videos/{request_id} em intervalos regulares e recupera o vídeo editado quando o estado muda para done. Em Python, os dois primeiros passos cabem em poucas linhas.

import httpx

# 1. Submit the edit
response = httpx.post(
    "https://api.x.ai/v1/videos/edits",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "grok-imagine-video",
        "prompt": "Add a rain effect over the entire scene",
        "video": {"url": "https://example.com/source.mp4"}
    }
)
request_id = response.json()["request_id"]

# 2. Poll the status (simplified)
status = httpx.get(
    f"https://api.x.ai/v1/videos/{request_id}",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

Defina o que muda e o que permanece

A xAI descreve o comportamento do modelo numa frase: o grok-imagine-video aplica a alteração solicitada e mantém tudo o resto tão próximo da origem quanto possível. A sua documentação deriva desta premissa uma diretriz: indique também o que deve permanecer idêntico. Os seus próprios exemplos focam-se igualmente em edições precisas de um único clipe — adicionar um colar de prata, mudar uma roupa para vermelho, colocar um chapéu preto de abas largas num personagem — executados em paralelo na mesma origem.

{
  "model": "grok-imagine-video",
  "prompt": "Change the woman's jacket to red. Keep the same face, the same setting, the same framing, and the same movement.",
  "video": {"url": "https://example.com/video.mp4"}
}

O guia de instruções para imagem da xAI, escrito para imagens estáticas, especifica a ordem que funciona: a modificação primeiro, depois uma frase que bloqueia o que permanece estático. Uma edição que começa por “manter tudo” quase não altera nada, e uma edição que copia uma instrução completa de geração reinventa a cena.

Quatro hábitos evitam a maioria das armadilhas: mantenha as suas origens abaixo de 8,7 segundos, num codec suportado (H.264, H.265 ou AV1); nomeie o que deve permanecer intacto; teste uma modificação num clipe curto antes de a escalar; e lembre-se de que a edição usa o grok-imagine-video, cuja grelha de preços mostra uma tarifa única, 0,050 USD por segundo — uma ronda de testes custa o mesmo que a geração.

Pontos-chave

  • O endpoint POST /v1/videos/edits modifica um vídeo existente com base numa instrução, apenas com grok-imagine-video
  • A origem dura no máximo 8,7 segundos; o resultado mantém a sua duração, proporção e resolução (máximo de 720p)
  • O vídeo de origem deve ser um MP4 num codec suportado (H.264, H.265, AV1)
  • O pedido não tem nenhum campo duration, aspect_ratio ou resolution
  • Indique o que deve mudar e, depois, o que deve permanecer idêntico