Edição de vídeo com /v1/videos/edits
Nesta página
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
videoque 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.
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/editsmodifica um vídeo existente com base numa instrução, apenas comgrok-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_ratioouresolution - Indique o que deve mudar e, depois, o que deve permanecer idêntico