Extension vidéo avec /v1/videos/extensions
På denna sida
Leçon mise à jour le 2 novembre 2026 selon la référence de l’API vidéo xAI : l’extension reçoit la vidéo dans un objet
video({"url": ...}), exactement comme l’édition — le texte précédent affirmait le contraire — le résultat se lit dansvideo.url, et la source est limitée à 15 secondes. Sources : Extension vidéo · Référence vidéo.
Étendre une vidéo existante
Là où l’édition transforme une séquence sans en changer la durée, l’extension fait exactement l’inverse : elle allonge une vidéo en générant une suite cohérente avec ce qui précède. Cela résout le problème le plus courant de la génération vidéo : un clip réussi mais trop court, ou une scène qui mérite de se développer au-delà de sa durée initiale. Plutôt que de tout régénérer en espérant recréer le même rendu, tu pars de l’existant pour continuer.
Le point de terminaison POST /v1/videos/extensions
La requête ressemble à une demande de génération, avec l’ajout de la vidéo de départ.
{
"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
}
Le champ model reste grok-imagine-video, prompt décrit ce qui doit se passer dans la suite, l’objet video spécifie la vidéo à étendre (une url ou le file_id d’un fichier téléchargé, pour une source de 2 à 15 secondes), et duration définit la longueur de l’extension entre 2 et 10 secondes — la valeur par défaut est de 6 secondes. Contrairement à l’édition, tu reprends ici le contrôle de la durée. La vidéo retournée contient l’original suivi de l’extension : une source de 10 secondes étendue de 5 secondes donne une vidéo de 15 secondes.
Le tableau suivant résume ce qui sépare les deux points de terminaison, car la confusion est fréquente.
| Aspect | Édition (/edits) | Extension (/extensions) |
|---|---|---|
| Objectif | Modifier le contenu | Ajouter de la durée |
| Paramètre vidéo | Objet video (url ou file_id) | Objet video (url ou file_id) |
| Durée de la source | Max 8,7 s | 2 à 15 s |
| Durée de sortie | Identique à la source (Max 720p) | Source + 2 à 10 s |
| Contenu original | Modifié | Préservé |
Les deux points de terminaison de l’API REST reçoivent la vidéo de la même manière, dans un objet video avec une propriété url. Le SDK Python, en revanche, la prend comme paramètre video_url : ne copie pas ce nom de paramètre dans un corps JSON, l’API ne le reconnaîtrait pas. Ce qui distingue vraiment les deux points de terminaison, c’est la durée.
Trois façons de poursuivre une scène
Le cas le plus simple consiste à laisser ce qui se passe déjà se poursuivre. Le prompt reprend l’action en cours et l’étend sans rupture.
{
"model": "grok-imagine-video",
"prompt": "The character continues walking along the beach, waves rolling gently",
"video": {"url": "https://exemple.com/promenade.mp4"},
"duration": 6
}
Tu peux aussi introduire un changement, c’est-à-dire apporter un nouvel élément ou modifier la direction du regard. Cela donne une progression narrative à ta séquence.
{
"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
}
Troisième cas d’usage : la conclusion. Une courte extension qui clôt proprement la séquence, souvent avec un fondu.
{
"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
}
Enchaîner les extensions pour construire une séquence
Rien n’empêche d’étendre une vidéo plusieurs fois de suite. Chaque extension produit une nouvelle vidéo dont l’URL peut servir de source pour l’extension suivante, te permettant de construire une longue séquence via des segments successifs, chacun piloté par son propre prompt. Le script ci-dessous enchaîne trois extensions en réinjectant l’URL obtenue à chaque étape.
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}")
Cette élégance a un prix, au sens propre comme au figuré. Chaque extension est facturée séparément. La source ne peut pas dépasser 15 secondes, ce qui borne la chaîne : en partant de 5 secondes, la séquence atteint 20 secondes après trois extensions de 5 secondes, et une quatrième serait refusée. La cohérence visuelle se dégrade à travers les maillons, car chaque étape s’appuie sur une sortie déjà interprétée : au-delà de trois ou quatre extensions enchaînées, des dérives de couleur et de morphologie deviennent visibles. Et comme partout dans cette API, les URL sont temporaires — télécharge chaque version intermédiaire, sinon un échec en fin de chaîne t’obligera à tout reprendre depuis le début.
Le duo génération puis extension
Le motif le plus courant en production combine les deux points de terminaison. Tu génères d’abord une base courte de 3 secondes avec un prompt très précis, via POST /v1/videos/generations, ce qui te permet d’itérer sur l’esthétique de départ à moindre coût. Tu ajoutes ensuite 5 secondes de développement via POST /v1/videos/extensions, puis 4 secondes de conclusion via un second appel au même point de terminaison. Le résultat est une vidéo de 12 secondes construite segment par segment, où chaque partie a été validée avant d’engager la suivante — un contrôle qu’aucune génération unique de 12 secondes n’offrirait.
Viktiga punkter
- L’extension allonge une vidéo de 2 à 15 secondes d’un segment de 2 à 10 secondes (6 par défaut) et renvoie la vidéo complète
- La vidéo source va dans un objet
video(urloufile_id), comme pour l’édition ; le SDK Python la prend commevideo_url - L’enchaînement permet de créer de longues séquences étape par étape
- La cohérence se dégrade au-delà de 3 à 4 extensions successives
- Combine génération initiale et extensions pour un contrôle précis du contenu