Images et vidéos dans les batchs — Batch API : traitement en masse

Cours révisé le 2 novembre 2026 d’après la documentation de xAI : la remise batch est de 20 % sur les modèles texte éligibles (et non 50 %), les exemples suivent l’API REST et le SDK officiel xai-sdk (client.batch.* ; l’API Batch de xAI n’a pas le format de celle d’OpenAI, le SDK OpenAI ne s’y applique pas), et l’API Responses passe avant Chat Completions, endpoint hérité chez xAI. Sources : Batch API · Référence REST · Tarifs batch.

Génération multimodale en masse

La Batch API ne se limite pas au texte. Vous pouvez soumettre des générations et des éditions d’images, des générations, éditions et prolongations de vidéos. Cette capacité ouvre la porte à des pipelines multimodaux complets : rédigez des descriptions et produisez leurs visuels dans une seule opération.

Génération d’images en batch

L’endpoint /v1/images/generations fonctionne dans un batch comme en mode synchrone. Le format se choisit avec aspect_ratio, la définition avec resolution ("1k", "1.5k" ou "2k"), le nombre d’images avec n :

{"custom_id": "img-001", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Logo minimaliste pour une startup fintech, fond blanc, style vectoriel", "n": 1, "aspect_ratio": "1:1", "resolution": "1k"}}
{"custom_id": "img-002", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Illustration isométrique d'un datacenter", "n": 1, "aspect_ratio": "16:9", "resolution": "1k"}}

Édition d’images en batch

L’endpoint /v1/images/edits modifie une image existante, passée dans un objet image : une url (adresse publique ou données encodées en base64) ou le file_id d’un fichier téléversé.

{"custom_id": "edit-001", "method": "POST", "url": "/v1/images/edits", "body": {"model": "grok-imagine-image-2.0", "prompt": "Remplace l'arrière-plan par un fond blanc uni", "image": {"url": "https://example.com/photo.jpg"}}}

En mode batch, l’édition sert à traiter un catalogue : harmoniser les arrière-plans, ajouter un élément, appliquer la même retouche à des centaines de visuels.

Génération de vidéos en batch

L’endpoint /v1/videos/generations (ou /v1/videos) génère des vidéos de 1 à 15 secondes (duration, 8 par défaut), en 480p, 720p ou 1080p :

{"custom_id": "vid-001", "method": "POST", "url": "/v1/videos/generations", "body": {"model": "grok-imagine-video-1.5", "prompt": "Animation fluide d'un graphique en barres qui croît progressivement", "duration": 8, "resolution": "720p"}}

Le traitement vidéo étant plus lourd que le texte ou l’image, ces requêtes peuvent prendre plus de temps au sein du batch.

Édition et prolongation de vidéos

L’endpoint /v1/videos/edits modifie une vidéo existante, et /v1/videos/extensions la prolonge d’un segment de 2 à 10 secondes. La vidéo source se passe dans un objet video (URL d’un fichier .mp4, ou file_id) :

{"custom_id": "vid-edit-001", "method": "POST", "url": "/v1/videos/edits", "body": {"model": "grok-imagine-video", "prompt": "Passe la scène au ralenti", "video": {"url": "https://example.com/clip.mp4"}}}
{"custom_id": "vid-ext-001", "method": "POST", "url": "/v1/videos/extensions", "body": {"model": "grok-imagine-video", "prompt": "La caméra recule lentement et révèle un coucher de soleil", "video": {"url": "https://example.com/clip.mp4"}, "duration": 6}}

Avec le SDK Python

Le SDK prépare ces requêtes avec des méthodes dédiées, puis les ajoute au batch comme les requêtes texte :

from xai_sdk import Client

client = Client()
batch = client.batch.create(batch_name="visuels_catalogue")

requetes = [
    client.image.prepare(
        prompt="Photo produit d'un casque audio sans fil, fond sombre, éclairage studio",
        model="grok-imagine-image-2.0",
        batch_request_id="prod-42-img",
    ),
    client.video.prepare(
        prompt="Le casque tourne lentement sur un plateau, éclairage dramatique",
        model="grok-imagine-video-1.5",
        batch_request_id="prod-42-vid",
    ),
]
client.batch.add(batch_id=batch.batch_id, batch_requests=requetes)

Tarification des contenus multimodaux

Point important : la remise batch ne concerne que les modèles texte éligibles. Les images et les vidéos sont facturées au tarif standard, même en mode batch — au 2 novembre 2026, 0,04 $ l’image avec grok-imagine-image-2.0 (0,02 $ avec grok-imagine-image), et 0,08 $ la seconde de vidéo avec grok-imagine-video-1.5 (0,02 $ en version -lite, 0,05 $ avec grok-imagine-video).

L’intérêt du batch pour le multimodal n’est donc pas tarifaire mais opérationnel : soumettre des centaines de générations en une opération, sans gérer autant d’appels ni buter sur les limites de débit.

Expiration des URL de résultats

Les résultats d’images et de vidéos sont fournis sous forme d’URL signées qui expirent au bout d’une heure. C’est une contrainte critique : téléchargez les fichiers dès que vous récupérez les résultats.

import mimetypes

import requests


def telecharger_medias(resultats, dossier):
    """Télécharge les images et vidéos dès la récupération des résultats."""
    for r in resultats:
        reponse = r.proto.response
        if reponse.HasField("image_response"):
            url = r.image_response.url
        elif reponse.HasField("video_response"):
            url = r.video_response.url
        else:
            continue  # résultat texte
        fichier = requests.get(url, timeout=120)
        fichier.raise_for_status()
        type_mime = fichier.headers.get("Content-Type", "").split(";")[0]
        extension = mimetypes.guess_extension(type_mime) or ".bin"
        with open(f"{dossier}/{r.batch_request_id}{extension}", "wb") as f:
            f.write(fichier.content)

Ne stockez jamais les URL signées pour un usage ultérieur : sauvegardez les fichiers dans votre propre stockage (S3, GCS, disque local).

Pipeline multimodal mixte

Un cas d’usage concret : produire des fiches produits complètes, texte et visuel, dans le même batch :

{"custom_id": "prod-42-desc", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "Rédige une description commerciale pour un casque audio sans fil haut de gamme.", "max_output_tokens": 300}}
{"custom_id": "prod-42-img", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Photo produit d'un casque audio sans fil premium, fond dégradé sombre, éclairage studio"}}

Un préfixe commun dans les identifiants (prod-42-desc, prod-42-img) permet de regrouper facilement les résultats texte et image d’un même produit.

Points clés à retenir

Images (génération, édition) et vidéos (génération, édition, prolongation) passent en batch
Les paramètres sont ceux de l’API : aspect_ratio, resolution, objets image et video
Images et vidéos restent au tarif standard, sans remise batch
Les URL signées des résultats expirent au bout d’une heure : téléchargez immédiatement
Un préfixe commun dans les identifiants regroupe les résultats d’un même produit