Extensão de vídeo com /v1/videos/extensions
Nesta página
Lição atualizada em 2 de novembro de 2026 com base na referência da API de Vídeo da xAI: a extensão recebe o vídeo num objeto
video({"url": ...}), exatamente como a edição — o texto anterior afirmava o contrário —, o resultado é lido emvideo.urle a fonte está limitada a 15 segundos. Fontes: Extensão de Vídeo · Referência de Vídeo.
Extender um vídeo existente
Enquanto a edição transforma uma sequência sem alterar a sua duração, a extensão faz exatamente o oposto: alonga um vídeo ao gerar uma continuação coerente com o que veio antes. Isto resolve o problema mais comum na geração de vídeo: um clipe bem-sucedido que é demasiado curto, ou uma cena que merece desenvolver-se para além da sua duração inicial. Em vez de regenerar tudo e esperar recriar o mesmo aspeto, parte-se do que já existe para continuar.
O endpoint POST /v1/videos/extensions
O pedido assemelha-se a um pedido de geração, com a adição do vídeo inicial.
{
"model": "grok-imagine-video",
"prompt": "Continue the scene with a zoom out revealing the full landscape",
"video": {"url": "https://exemple.com/video-courte.mp4"},
"duration": 5
}
O campo model mantém-se como grok-imagine-video, o prompt descreve o que deve acontecer na continuação, o objeto video especifica o vídeo a estender (um url ou o file_id de um ficheiro carregado, para uma fonte de 2 a 15 segundos) e duration define a duração da extensão entre 2 e 10 segundos — o padrão é 6 segundos. Ao contrário da edição, recupera aqui o controlo sobre a duração. O vídeo devolvido contém o original seguido da extensão: uma fonte de 10 segundos estendida em 5 segundos resulta num vídeo de 15 segundos.
A tabela seguinte resume o que separa os dois endpoints, uma vez que a confusão é comum.
| Aspeto | Edição (/edits) | Extensão (/extensions) |
|---|---|---|
| Objetivo | Modificar conteúdo | Adicionar duração |
| Parâmetro de vídeo | Objeto video (url ou file_id) | Objeto video (url ou file_id) |
| Duração da fonte | Máx. 8,7 s | 2 a 15 s |
| Duração de saída | Igual à fonte (Máx. 720p) | Fonte + 2 a 10 s |
| Conteúdo original | Modifica | Preserva |
Ambos os endpoints da API REST recebem o vídeo da mesma forma, num objeto video com uma propriedade url. O SDK Python, no entanto, aceita-o como parâmetro video_url: não copie este nome de parâmetro para um corpo JSON, pois a API não o reconhecerá. O que verdadeiramente distingue os dois endpoints é a duração.
Três formas de continuar uma cena
O caso mais simples consiste em deixar que o que já está a acontecer continue. O prompt retoma a ação atual e estende-a sem rutura.
{
"model": "grok-imagine-video",
"prompt": "The character continues walking along the beach, waves rolling gently",
"video": {"url": "https://exemple.com/promenade.mp4"},
"duration": 6
}
Pode também introduzir uma mudança, ou seja, trazer um novo elemento ou modificar a direção da visão. Isto confere à sequência uma progressão narrativa.
{
"model": "grok-imagine-video",
"prompt": "The camera pivots right revealing a lighthouse in the distance, the lighthouse beam starts to rotate",
"video": {"url": "https://exemple.com/plage.mp4"},
"duration": 8
}
Terceiro caso de uso: a conclusão. Uma extensão curta que encerra a sequência de forma limpa, muitas vezes com um desvanecimento (fade).
{
"model": "grok-imagine-video",
"prompt": "The scene ends with a gradual fade to black, the last glimmers of sunlight disappear on the horizon",
"video": {"url": "https://exemple.com/coucher-soleil.mp4"},
"duration": 4
}
Encadear extensões para construir uma sequência
Nada impede de estender um vídeo várias vezes seguidas. Cada extensão produz um novo vídeo cujo URL pode servir de fonte para a extensão seguinte, permitindo construir uma sequência longa através de segmentos sucessivos, cada um orientado pelo seu próprio prompt. O script abaixo encadeia três extensões, reinjetando o URL obtido em cada passo.
import httpx
import time
api_key = "your_key"
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
def attendre_video(request_id):
"""Poll status until completion."""
while True:
resp = httpx.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
).json()
if resp["status"] == "done":
return resp["video"]["url"]
if resp["status"] == "failed":
raise RuntimeError(f"Generation failed: {resp.get('error')}")
time.sleep(5)
# Base video
video_url = "https://exemple.com/video-initiale.mp4"
# Chain 3 extensions
prompts = [
"The character crosses the bridge, profile view",
"He stops in the middle and looks at the river below",
"He resumes walking toward the other bank, the camera follows"
]
for prompt in prompts:
resp = httpx.post(
"https://api.x.ai/v1/videos/extensions",
headers=headers,
json={
"model": "grok-imagine-video",
"prompt": prompt,
"video": {"url": video_url},
"duration": 5
}
).json()
video_url = attendre_video(resp["request_id"])
print(f"Extension complete: {video_url}")
Esta elegância tem um preço, literal e figurativamente. Cada extensão é faturada separadamente. A fonte não pode exceder 15 segundos, o que limita a cadeia: começando com 5 segundos, a sequência atinge 20 segundos após três extensões de 5 segundos, e uma quarta seria recusada. A coerência visual degrada-se ao longo dos elos, pois cada passo depende de um resultado já interpretado: além de três ou quatro extensões encadeadas, tornam-se visíveis desvios de cor e morfologia. E como em toda esta API, os URLs são temporários — descarregue cada versão intermédia, caso contrário, uma falha no final da cadeia obrigá-lo-á a recomeçar desde o início.
A dupla geração e depois extensão
O padrão mais comum em produção combina ambos os endpoints. Primeiro gera uma base curta de 3 segundos com um prompt muito preciso, via POST /v1/videos/generations, permitindo iterar sobre a estética inicial a um custo menor. Em seguida, adiciona 5 segundos de desenvolvimento via POST /v1/videos/extensions e depois 4 segundos de conclusão através de uma segunda chamada ao mesmo endpoint. O resultado é um vídeo de 12 segundos construído segmento a segmento, onde cada parte foi validada antes de se iniciar a seguinte — um controlo que nenhuma geração única de 12 segundos ofereceria.
Pontos-chave
- A extensão alonga um vídeo de 2 a 15 segundos com um segmento de 2 a 10 segundos (padrão 6) e devolve o vídeo completo
- O vídeo de fonte coloca-se num objeto
video(urloufile_id), tal como na edição; o SDK Python aceita-o comovideo_url - O encadeamento permite criar sequências longas passo a passo
- A coerência degrada-se além de 3-4 extensões sucessivas
- Combine geração inicial + extensões para um controlo preciso do conteúdo