5 méthodes pour résoudre l’erreur de dimension de l’image de référence de l’API Sora 2 : Guide de dépannage complet Inpaint image must match

Lors de l'utilisation de l'API Sora 2 pour la génération de vidéo à partir d'image (Image-to-Video), l'incohérence des dimensions de l'image de référence est l'une des erreurs les plus fréquentes rencontrées par les développeurs. Cet article analyse en détail la cause profonde de l'erreur Inpaint image must match the requested width and height et propose 5 solutions éprouvées.

Valeur ajoutée : À la fin de cet article, vous maîtriserez les règles de vérification des dimensions de l'image de référence de l'API Sora 2 et saurez comment utiliser Python Pillow et FFmpeg pour prétraiter vos images, résolvant ainsi définitivement les erreurs de dimensions.

Analyse de l'erreur de dimension de l'image de référence Sora 2 API

Lorsque vous appelez la fonction de génération de vidéo à partir d'image de l'API Sora 2, si vous voyez le message d'erreur suivant :

{
  "error": {
    "message": "Inpaint image must match the requested width and height",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Cela signifie que les dimensions de l'image que vous avez téléchargée (input_reference) ne correspondent pas à la résolution vidéo cible.

Règles de correspondance stricte des dimensions de l'API Sora 2

L'API Sora 2 impose un mécanisme de vérification rigoureux pour les images de référence :

Résolutions vidéo supportées par l'API Sora 2

Selon la documentation officielle d'OpenAI, l'API Sora 2 supporte actuellement les résolutions suivantes :

🎯 Note importante : Votre image de référence doit être exactement de la même dimension que la résolution cible choisie. Par exemple, si vous choisissez une résolution de 1280×720, l'image doit faire précisément 1280×720 pixels. Un écart d'un seul pixel provoquera une erreur.

5 solutions pour les erreurs de dimensions d'image de référence de l'API Sora 2

Solution 1 : Remplissage et recadrage intelligent avec Python Pillow

L'utilisation de la méthode ImageOps.pad() de Pillow permet de traiter intelligemment n'importe quelle dimension d'image, en conservant le format d'image (aspect ratio) tout en remplissant jusqu'à la taille cible :

from PIL import Image, ImageOps
import openai

# Résolutions standards supportées par l'API Sora 2
SORA_RESOLUTIONS = {
    "landscape_720p": (1280, 720),
    "portrait_720p": (720, 1280),
    "landscape_1080p": (1792, 1024),
    "portrait_1080p": (1024, 1792),
}

def preprocess_image_for_sora(image_path, target_resolution="landscape_720p"):
    """Prétraite l'image pour correspondre aux exigences de dimensions de l'API Sora 2"""
    target_size = SORA_RESOLUTIONS[target_resolution]

    # Ouvrir l'image originale
    img = Image.open(image_path)

    # Utiliser la méthode pad : conserver le ratio, remplir avec un fond noir
    processed = ImageOps.pad(img, target_size, color=(0, 0, 0))

    # Enregistrer l'image traitée
    output_path = image_path.replace(".jpg", "_sora_ready.jpg")
    processed.save(output_path, "JPEG", quality=95)

    return output_path

# Exemple d'utilisation
processed_image = preprocess_image_for_sora("my_image.jpg", "landscape_720p")

# Appeler l'API Sora 2 - via l'interface unifiée APIYI
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Utilisation de l'interface unifiée APIYI
)

with open(processed_image, "rb") as f:
    response = client.videos.create(
        model="sora-2",
        prompt="A serene landscape comes to life",
        size="1280x720",
        input_reference=f
    )

🚀 Démarrage rapide : Nous vous recommandons d'utiliser la plateforme APIYI (apiyi.com) pour tester rapidement l'API Sora 2. Elle propose une interface prête à l'emploi, permettant une intégration sans configurations complexes.

Solution 2 : Recadrage centré avec Python Pillow (conserver le sujet)

Si vous souhaitez conserver le contenu principal de l'image sans avoir de bandes noires de remplissage, vous pouvez utiliser le recadrage centré :

from PIL import Image

def center_crop_for_sora(image_path, target_width, target_height):
    """Recadre l'image par le centre pour correspondre aux dimensions de l'API Sora 2"""
    img = Image.open(image_path)
    orig_width, orig_height = img.size

    # Calculer le ratio cible
    target_ratio = target_width / target_height
    orig_ratio = orig_width / orig_height

    if orig_ratio > target_ratio:
        # L'image d'origine est plus large, redimensionner selon la hauteur puis recadrer les côtés
        new_height = target_height
        new_width = int(orig_width * (target_height / orig_height))
    else:
        # L'image d'origine est plus haute, redimensionner selon la largeur puis recadrer le haut et le bas
        new_width = target_width
        new_height = int(orig_height * (target_width / orig_width))

    # D'abord redimensionner
    img = img.resize((new_width, new_height), Image.LANCZOS)

    # Puis recadrer au centre
    left = (new_width - target_width) // 2
    top = (new_height - target_height) // 2
    right = left + target_width
    bottom = top + target_height

    cropped = img.crop((left, top, right, bottom))

    output_path = image_path.replace(".jpg", f"_{target_width}x{target_height}.jpg")
    cropped.save(output_path, "JPEG", quality=95)

    return output_path

# Préparer l'image de référence pour une vidéo 720p en mode paysage
processed = center_crop_for_sora("my_photo.jpg", 1280, 720)

Solution 3 : Traitement par lot en ligne de commande avec FFmpeg

Pour les scénarios nécessitant un traitement par lot, FFmpeg est un choix plus efficace :

Mode recadrage centré (Cover) :

# Redimensionner en gardant le ratio, puis recadrer au centre aux dimensions cibles
ffmpeg -i input.jpg -vf "scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720" output_sora.jpg

Mode remplissage (Letterbox) :

# Garder le ratio d'origine, remplir en noir les zones vides
ffmpeg -i input.jpg -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2:black" output_sora.jpg

Script de traitement par lot :

#!/bin/bash
# Traiter par lot toutes les images jpg du répertoire actuel au format paysage 720p pour l'API Sora 2

for file in *.jpg; do
    ffmpeg -i "$file" \
        -vf "scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720" \
        -q:v 2 \
        "sora_ready_$file"
done

Solution 4 : Utilisation du paramètre crop_bounds (recadrage intégré à l'API)

L'API Sora 2 propose le paramètre crop_bounds, qui permet de spécifier la zone de recadrage directement au niveau de l'API :

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Utilisation de l'interface unifiée APIYI
)

# Utiliser crop_bounds pour spécifier la zone de recadrage (sous forme de ratios)
with open("full_size_image.jpg", "rb") as f:
    response = client.videos.create(
        model="sora-2",
        prompt="Effet vidéo dynamique",
        size="1280x720",
        input_reference=f,
        crop_bounds={
            "left_fraction": 0.1,    # Coupe 10% à gauche
            "top_fraction": 0.1,     # Coupe 10% en haut
            "right_fraction": 0.9,   # Garde jusqu'à 90% à droite
            "bottom_fraction": 0.9   # Garde jusqu'à 90% en bas
        },
        frame_index=0  # L'image sert de première image
    )

⚠️ Attention : Lors de l'utilisation de crop_bounds, la zone recadrée doit toujours correspondre à la résolution vidéo cible. Il est recommandé de l'utiliser en complément d'un prétraitement en amont.

Solution 5 : Classe utilitaire complète de prétraitement d'image

Voici une classe utilitaire de prétraitement d'image de niveau production, incluant plusieurs modes de traitement :

from PIL import Image, ImageOps
from pathlib import Path
import io

class SoraImagePreprocessor:
    """Outil de prétraitement d'image de référence pour l'API Sora 2"""

    RESOLUTIONS = {
        "1280x720": (1280, 720),
        "720x1280": (720, 1280),
        "1792x1024": (1792, 1024),
        "1024x1792": (1024, 1792),
    }

    def __init__(self, target_resolution="1280x720"):
        if target_resolution not in self.RESOLUTIONS:
            raise ValueError(f"Résolution non supportée : {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def pad(self, image_path, bg_color=(0, 0, 0)):
        """Mode remplissage : conserve le ratio d'origine, ajoute une couleur de fond"""
        img = Image.open(image_path)
        return ImageOps.pad(img, self.target_size, color=bg_color)

    def cover(self, image_path):
        """Mode couverture : conserve le ratio d'origine, recadre au centre"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def stretch(self, image_path):
        """Mode étirement : force l'étirement aux dimensions cibles (non recommandé)"""
        img = Image.open(image_path)
        return img.resize(self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """Convertit une image PIL en flux d'octets pour l'upload via l'API"""
        buffer = io.BytesIO()
        img.save(buffer, format=format, quality=quality)
        buffer.seek(0)
        return buffer

    def process_and_save(self, image_path, mode="cover", output_path=None):
        """Traite et enregistre l'image"""
        if mode == "pad":
            processed = self.pad(image_path)
        elif mode == "cover":
            processed = self.cover(image_path)
        elif mode == "stretch":
            processed = self.stretch(image_path)
        else:
            raise ValueError(f"Mode non supporté : {mode}")

        if output_path is None:
            p = Path(image_path)
            output_path = p.parent / f"{p.stem}_sora_{self.target_size[0]}x{self.target_size[1]}{p.suffix}"

        processed.save(output_path, quality=95)
        return output_path

# Exemple d'utilisation
preprocessor = SoraImagePreprocessor("1280x720")

# Option 1 : Traiter et enregistrer
output = preprocessor.process_and_save("my_image.jpg", mode="cover")
print(f"Traitement terminé : {output}")

# Option 2 : Obtenir directement le flux d'octets pour l'appel API
img = preprocessor.cover("my_image.jpg")
image_bytes = preprocessor.to_bytes(img)

import openai
from PIL import Image, ImageOps
import io

class SoraImagePreprocessor:
    """Outil de prétraitement d'image de référence pour l'API Sora 2"""

    RESOLUTIONS = {
        "1280x720": (1280, 720),
        "720x1280": (720, 1280),
        "1792x1024": (1792, 1024),
        "1024x1792": (1024, 1792),
    }

    def __init__(self, target_resolution="1280x720"):
        if target_resolution not in self.RESOLUTIONS:
            raise ValueError(f"Résolution non supportée : {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def cover(self, image_path):
        """Mode couverture : conserve le ratio d'origine, recadre au centre"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """Convertit une image PIL en flux d'octets"""
        buffer = io.BytesIO()
        img.save(buffer, format=format, quality=quality)
        buffer.seek(0)
        return buffer


def generate_video_with_image(image_path, prompt, resolution="1280x720"):
    """
    Génère une vidéo Sora 2 en utilisant une image prétraitée

    Args:
        image_path: Chemin de l'image originale
        prompt: Invite de description de la vidéo
        resolution: Résolution cible

    Returns:
        ID de la tâche de génération vidéo
    """
    # 1. Prétraiter l'image
    preprocessor = SoraImagePreprocessor(resolution)
    processed_img = preprocessor.cover(image_path)
    image_bytes = preprocessor.to_bytes(processed_img)

    # 2. Initialiser le client - via l'interface unifiée APIYI
    client = openai.OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    # 3. Appeler l'API Sora 2
    response = client.videos.create(
        model="sora-2",
        prompt=prompt,
        size=resolution,
        input_reference=image_bytes,
        duration=5  # Durée de la vidéo (en secondes)
    )

    return response


# Exemple d'appel complet
if __name__ == "__main__":
    result = generate_video_with_image(
        image_path="landscape_photo.jpg",
        prompt="The scene comes alive with gentle wind moving through the trees",
        resolution="1280x720"
    )
    print(f"Tâche de génération vidéo soumise : {result}")

Comparaison des modes de prétraitement d'image pour l'API Sora 2

Le choix du mode de prétraitement approprié est essentiel pour le rendu final de vos vidéos :

Comparaison des modes de prétraitement Originale 4:3 → Cible 16:9 (1280×720)

Originale 1600×1200 Format 4:3

Mode Pad (Remplissage)

✓ Contenu intégral préservé Bandes noires latérales

Mode Cover (Recadrage)

✓ Plein écran sans bandes Haut et bas recadrés

Mode Stretch (Étirage)

Distorsion !

✗ Image fortement déformée Non recommandé

Critères Pad Cover Stretch

Intégrité de l’image ★★★★★ ★★★☆☆ ★★★★★

Effet visuel ★★★☆☆ ★★★★★ ★☆☆☆☆

Scénarios Produits / Art Portraits / Paysages Non recommandé

Recommandation Recommandé ✓ Premier choix ★ À éviter ✗

💡 Conseil de sélection : Le choix du mode dépend principalement du contenu de votre image et du rendu souhaité. Nous vous recommandons d'effectuer des tests sur la plateforme APIYI (apiyi.com) pour comparer rapidement les résultats entre les différents modes.

Modes recommandés par scénario

FAQ sur l'image de référence (垫图) pour l'API Sora 2

# Paramètres de traitement haute qualité
img = img.resize(target_size, Image.LANCZOS)  # Utilisation de l'algorithme Lanczos
img.save(output_path, "JPEG", quality=95)     # Sauvegarde en haute qualité

from concurrent.futures import ThreadPoolExecutor
import os

def batch_process(image_dir, output_dir, resolution="1280x720"):
    preprocessor = SoraImagePreprocessor(resolution)

    def process_single(filename):
        input_path = os.path.join(image_dir, filename)
        output_path = os.path.join(output_dir, f"sora_{filename}")
        return preprocessor.process_and_save(input_path, "cover", output_path)

    image_files = [f for f in os.listdir(image_dir) if f.endswith(('.jpg', '.png'))]

    with ThreadPoolExecutor(max_workers=4) as executor:
        results = list(executor.map(process_single, image_files))

    return results

Tableau de référence rapide des dimensions pour l'API Sora 2

Pour faciliter vos recherches rapides, voici le tableau complet de correspondance des dimensions :

📌 Note : Les plateformes disponibles incluent APIYI (apiyi.com), l'API officielle d'OpenAI, etc. Il est conseillé de choisir une plateforme offrant une vitesse de réponse rapide et des tarifs avantageux pour vos tests de développement.

Résumé

L'erreur de dimensions de l'image de référence (image source) avec l'API Sora 2 est l'un des problèmes les plus fréquents rencontrés par les développeurs. L'approche principale pour résoudre cela consiste à :

1. Comprendre les règles : l'image de référence doit avoir des dimensions identiques (au pixel près) à celles de la vidéo cible.
2. Choisir le mode : sélectionnez le mode Pad ou Cover en fonction du contenu de l'image.
3. Prétraitement : utilisez Python Pillow ou FFmpeg pour le traitement préalable.
4. Vérifier les dimensions : assurez-vous que les dimensions de l'image correspondent parfaitement après le traitement.

Nous vous recommandons d'utiliser APIYI (apiyi.com) pour tester rapidement l'efficacité de votre prétraitement d'image et la qualité de la génération vidéo.

Auteur : Équipe APIYI | Pour plus d'astuces sur le développement IA, visitez apiyi.com

Références :

1. Documentation API OpenAI Sora : Instructions pour l'interface Image-to-Video (Image-vers-Vidéo)
   • Lien : platform.openai.com/docs/guides/video-generation
2. Documentation officielle de Pillow : Module de traitement d'image ImageOps
   • Lien : pillow.readthedocs.io/en/stable/reference/ImageOps.html
3. Documentation officielle de FFmpeg : Filtres de traitement vidéo et image
   • Lien : ffmpeg.org/ffmpeg-filters.html