Édition de vidéo avec /v1/videos/edits

Modifier une vidéo existante

Générer n’est qu’une partie du travail. L’API xAI expose également un endpoint d’édition vidéo capable de reprendre une séquence existante et de la modifier à partir d’instructions écrites. C’est l’équivalent vidéo de l’édition d’image, avec un tempérament propre : plus contraint sur les formats, mais redoutablement efficace sur les transformations globales. Avant de rédiger votre première requête, notez les quatre bornes qui décideront de ce que vous pouvez lui soumettre.

L’endpoint POST /v1/videos/edits

La requête associe une vidéo source à un prompt décrivant la modification attendue.

{
  "model": "grok-imagine-video",
  "prompt": "Change l'arrière-plan en un coucher de soleil sur la mer",
  "video": {
    "url": "https://exemple.com/video-originale.mp4"
  }
}

Trois champs suffisent : model, qui reste grok-imagine-video ; prompt, qui porte la description de la modification ; et video.url, qui pointe vers le fichier MP4 à traiter. Remarquez que la vidéo est encapsulée dans un objet — ce détail de syntaxe prendra tout son sens à la leçon suivante, où l’endpoint d’extension adopte une convention différente.

Les contraintes techniques sont ici plus serrées qu’en génération. La durée maximale en sortie est de 8.7 secondes : si votre source est plus longue, seules les premières 8.7 secondes seront traitées, et le reste sera simplement perdu. La résolution plafonne à 720p. Le fichier d’entrée doit être un MP4 avec un codec H.265, H.264, AV1 ou compatible. Point le plus déroutant pour qui vient de la génération : vous n’avez aucun contrôle sur la durée, le ratio ou la résolution de sortie, tous déterminés par la vidéo source. Envoyer un aspect_ratio dans une requête d’édition n’a donc aucun effet.

Ce que l’on demande à une édition

Le remplacement d’arrière-plan est le cas d’école : le sujet reste, le décor change.

{
  "model": "grok-imagine-video",
  "prompt": "Remplace l'arriere-plan par un paysage spatial avec des etoiles et des nebuleuses",
  "video": {"url": "https://exemple.com/video.mp4"}
}

Le changement de style opère sur l’image entière et transforme le registre du clip sans en modifier l’action — pratique pour décliner une même séquence en plusieurs univers.

{
  "model": "grok-imagine-video",
  "prompt": "Transforme cette video en style dessin anime japonais avec des couleurs vives",
  "video": {"url": "https://exemple.com/video.mp4"}
}

L’ajout d’éléments enrichit la scène de couches qui n’existaient pas au tournage, généralement atmosphériques.

{
  "model": "grok-imagine-video",
  "prompt": "Ajoute de la neige qui tombe et un effet de givre sur les bords",
  "video": {"url": "https://exemple.com/video.mp4"}
}

La modification d’éclairage, enfin, revient à réétalonner la séquence : mêmes plans, ambiance radicalement différente.

{
  "model": "grok-imagine-video",
  "prompt": "Change l'eclairage pour une ambiance nuit avec des lumieres neon bleues et violettes",
  "video": {"url": "https://exemple.com/video.mp4"}
}

Le cycle asynchrone, identique à la génération

L’édition suit exactement le même protocole en quatre temps que la génération : vous envoyez la requête, vous recevez un request_id, vous interrogez GET /v1/videos/{request_id} à intervalles réguliers, et vous récupérez la vidéo éditée quand le statut passe à done. En Python, les deux premières étapes tiennent en quelques lignes.

import httpx

# 1. Soumettre l'edition
response = httpx.post(
    "https://api.x.ai/v1/videos/edits",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "grok-imagine-video",
        "prompt": "Ajoute un effet de pluie sur toute la scène",
        "video": {"url": "https://exemple.com/source.mp4"}
    }
)
request_id = response.json()["request_id"]

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

Savoir ce que l’on peut raisonnablement demander

L’expérience dessine une frontière assez nette. L’édition excelle sur les changements de style globaux — anime, peinture, noir et blanc —, sur les modifications d’éclairage et d’ambiance, et sur l’ajout d’éléments atmosphériques comme la pluie, la neige ou la brume. Elle est en revanche peu fiable dès qu’il faut retoucher un élément précis dans la scène, remplacer un objet complexe, ou imposer un changement qui contredit le mouvement déjà présent dans les images.

Quatre réflexes évitent la majorité des déconvenues : gardez vos sources sous 8.7 secondes pour que la totalité soit traitée, préférez les codecs H.265 ou H.264 pour la compatibilité, testez sur des clips courts avant d’engager des vidéos plus longues, et rappelez-vous que l’édition est facturée au même tarif que la génération — un aller-retour d’essais s’y chiffre exactement de la même manière.

Points clés à retenir

• L’endpoint POST /v1/videos/edits modifie une vidéo existante selon un prompt
• La durée maximale en sortie est de 8.7 secondes
• La vidéo source doit être en MP4 avec un codec compatible (H.265, H.264, AV1)
• Pas de contrôle sur la durée, le ratio ou la résolution en sortie
• Les changements de style et d’ambiance donnent les meilleurs résultats