Extension de vidéo avec /v1/videos/extensions

Leçon corrigée le 2 novembre 2026 d’après la référence de l’API vidéo de xAI : l’extension reçoit la vidéo dans un objet video ({"url": ...}), exactement comme l’édition — l’ancien texte affirmait l’inverse —, le résultat se lit dans video.url, et la source est limitée à 15 secondes. Sources : Video Extension · Référence Videos.

Prolonger une vidéo existante

Là où l’édition transforme une séquence sans en changer la longueur, 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. C’est la réponse au problème le plus banal de la génération vidéo — un clip réussi mais trop court, ou une scène qui mériterait de se développer au-delà de sa durée initiale. Plutôt que de tout régénérer en espérant retrouver le même rendu, vous partez de ce qui existe et vous continuez.

L’endpoint POST /v1/videos/extensions

La requête ressemble à celle d’une génération, avec la vidéo de départ en plus.

{
  "model": "grok-imagine-video",
  "prompt": "Continue la scène avec un zoom arrière révélant le paysage complet",
  "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 désigne la vidéo à prolonger (une url ou le file_id d’un fichier téléversé, pour une source de 2 à 15 secondes), et duration fixe la longueur de l’extension entre 2 et 10 secondes — la valeur par défaut étant 6 secondes. Contrairement à l’édition, vous récupérez donc ici la maîtrise de la durée. La vidéo renvoyée contient l’original suivi de l’extension : une source de 10 secondes prolongée de 5 donne une vidéo de 15 secondes.

Le tableau suivant résume ce qui sépare les deux endpoints, car la confusion est fréquente.

Les deux endpoints de l’API REST reçoivent la vidéo de la même façon, dans un objet video doté d’une propriété url. Le SDK Python, lui, la prend en paramètre video_url : ne recopiez pas ce nom de paramètre dans un corps JSON, l’API ne le reconnaît pas. Ce qui distingue vraiment les deux endpoints, ce sont les durées.

Trois façons de continuer une scène

Le cas le plus simple consiste à laisser courir ce qui est déjà en train de se produire. Le prompt reprend l’action en cours et la prolonge sans rupture.

{
  "model": "grok-imagine-video",
  "prompt": "Le personnage continue sa marche le long de la plage, les vagues deferlent doucement",
  "video": {"url": "https://exemple.com/promenade.mp4"},
  "duration": 6
}

Vous pouvez aussi introduire un changement, c’est-à-dire faire entrer un élément nouveau ou modifier la direction du regard. C’est ce qui donne à une séquence sa progression narrative.

{
  "model": "grok-imagine-video",
  "prompt": "La camera pivote vers la droite révélant un phare au loin, la lumière du phare commence a tourner",
  "video": {"url": "https://exemple.com/plage.mp4"},
  "duration": 8
}

Troisième usage, la conclusion : une extension courte qui referme la séquence proprement, souvent par un fondu.

{
  "model": "grok-imagine-video",
  "prompt": "La scène se termine avec un fondu progressif vers le noir, les dernières lueurs du soleil disparaissent a l'horizon",
  "video": {"url": "https://exemple.com/coucher-soleil.mp4"},
  "duration": 4
}

Chaî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 à l’extension suivante, ce qui vous permet de bâtir une séquence longue par segments successifs, chacun piloté par son propre prompt. Le script ci-dessous enchaîne trois extensions en réinjectant à chaque tour l’URL obtenue.

import httpx
import time

api_key = "votre_cle"
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

def attendre_video(request_id):
    """Interroge le statut jusqu'a 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"Génération échouée : {resp.get('error')}")
        time.sleep(5)

# Video de base
video_url = "https://exemple.com/video-initiale.mp4"

# Chainer 3 extensions
prompts = [
    "Le personnage traverse le pont, vue de profil",
    "Il s'arrete au milieu et regarde la riviere en contrebas",
    "Il reprend sa marche vers l'autre rive, la camera le suit"
]

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 terminee : {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 dépasser 15 secondes, ce qui borne la chaîne : partie de 5 secondes, la séquence atteint 20 secondes après trois extensions de 5, et une quatrième serait refusée. La cohérence visuelle se dégrade au fil des maillons, puisque chaque étape s’appuie sur une sortie déjà interprétée : au-delà de trois ou quatre extensions enchaînées, les dérives de couleur et de morphologie deviennent visibles. Et comme partout dans cette API, les URL sont temporaires — téléchargez chaque version intermédiaire, sans quoi un échec en fin de chaîne vous obligera à tout reprendre depuis le début.

Le duo génération puis extension

Le schéma le plus répandu en production combine les deux endpoints. Vous générez d’abord une base courte de 3 secondes avec un prompt très précis, via POST /v1/videos/generations, ce qui vous permet d’itérer à moindre coût sur l’esthétique de départ. Vous ajoutez ensuite 5 secondes de développement par POST /v1/videos/extensions, puis 4 secondes de conclusion par un second appel au même endpoint. Le résultat est une vidéo de 12 secondes construite segment par segment, où chaque partie a été validée avant que la suivante ne soit engagée — un contrôle qu’aucune génération unique de 12 secondes ne vous offrirait.

Points clés à retenir

• L’extension prolonge une vidéo de 2 à 15 secondes d’un segment de 2 à 10 secondes (défaut 6), et renvoie la vidéo complète
• La vidéo source se passe dans un objet video (url ou file_id), comme pour l’édition ; le SDK Python la prend en video_url
• Le chaînage permet de créer des séquences longues étape par étape
• La cohérence se dégrade au-delà de 3-4 extensions successives
• Combinez génération initiale + extensions pour un contrôle précis du contenu