5 Methoden zur Behebung des Sora 2 API Referenzbildgrößen-Fehlers: Inpaint image must match – Vollständiger Leitfaden zur Fehlerbehebung

Beim Einsatz der Sora 2 API für die Image-to-Video-Generierung (Bild-zu-Video) gehören nicht übereinstimmende Abmessungen des Referenzbildes zu den häufigsten Fehlermeldungen für Entwickler. In diesem Artikel analysieren wir detailliert die Ursache des Fehlers Inpaint image must match the requested width and height und stellen 5 praxiserprobte Lösungen vor.

Kernnutzen: Nach der Lektüre dieses Artikels werden Sie die Validierungsregeln für Referenzbilder der Sora 2 API verstehen und lernen, wie Sie Bilder mit Python (Pillow) und FFmpeg vorverarbeiten, um Dimensionsfehler endgültig zu beheben.

Sora 2 API: Ursachenanalyse für Dimensionsfehler

Wenn Sie die Image-to-Video-Funktion der Sora 2 API aufrufen und die folgende Fehlermeldung erhalten:

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

Dies bedeutet, dass die Abmessungen Ihres hochgeladenen Referenzbildes (input_reference) nicht mit der gewählten Videoauflösung übereinstimmen.

Sora 2 API: Strikte Regeln für Referenzbilder

Die Sora 2 API verfügt über einen strengen Validierungsmechanismus für Bilder:

Von der Sora 2 API unterstützte Videoauflösungen

Laut der offiziellen Dokumentation unterstützt die Sora 2 API derzeit folgende Auflösungen:

🎯 Wichtiger Hinweis: Ihr Referenzbild muss exakt der gewählten Zielauflösung entsprechen. Wenn Sie beispielsweise 1280×720 wählen, muss das Bild präzise 1280×720 Pixel groß sein. Schon eine Abweichung von nur 1 Pixel führt zu einem Fehler.

5 Lösungen für Sora 2 API Bildformat-Fehlermeldungen beim Referenzbild

Lösung 1: Intelligentes Zuschneiden und Auffüllen mit Python Pillow

Die Methode ImageOps.pad() von Pillow ermöglicht eine intelligente Verarbeitung von Bildern beliebiger Größe. Dabei wird das Seitenverhältnis beibehalten und das Bild auf die Zielgröße aufgefüllt:

from PIL import Image, ImageOps
import openai

# Von der Sora 2 API unterstützte Standardauflösungen
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"):
    """Bild vorverarbeiten, um den Größenanforderungen der Sora 2 API zu entsprechen"""
    target_size = SORA_RESOLUTIONS[target_resolution]

    # Originalbild öffnen
    img = Image.open(image_path)

    # Pad-Methode verwenden: Seitenverhältnis beibehalten, mit schwarzem Hintergrund auffüllen
    processed = ImageOps.pad(img, target_size, color=(0, 0, 0))

    # Verarbeitetes Bild speichern
    output_path = image_path.replace(".jpg", "_sora_ready.jpg")
    processed.save(output_path, "JPEG", quality=95)

    return output_path

# Anwendungsbeispiel
processed_image = preprocess_image_for_sora("my_image.jpg", "landscape_720p")

# Sora 2 API aufrufen - über die einheitliche Schnittstelle von APIYI
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Einheitliche APIYI Schnittstelle nutzen
)

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
    )

🚀 Schnellstart: Wir empfehlen die Plattform APIYI (apiyi.com) zum schnellen Testen der Sora 2 API. Die Plattform bietet sofort einsatzbereite Schnittstellen, mit denen die Integration ohne komplexe Konfiguration gelingt.

Lösung 2: Zentriertes Zuschneiden mit Python Pillow (Hauptmotiv erhalten)

Wenn Sie das Hauptmotiv des Bildes beibehalten möchten und keine schwarzen Ränder durch das Auffüllen wünschen, können Sie ein zentriertes Zuschneiden (Center Crop) verwenden:

from PIL import Image

def center_crop_for_sora(image_path, target_width, target_height):
    """Bild zentriert zuschneiden, um den Größenanforderungen der Sora 2 API zu entsprechen"""
    img = Image.open(image_path)
    orig_width, orig_height = img.size

    # Ziel-Seitenverhältnis berechnen
    target_ratio = target_width / target_height
    orig_ratio = orig_width / orig_height

    if orig_ratio > target_ratio:
        # Originalbild ist breiter: Nach Höhe skalieren und Seiten beschneiden
        new_height = target_height
        new_width = int(orig_width * (target_height / orig_height))
    else:
        # Originalbild ist höher: Nach Breite skalieren und oben/unten beschneiden
        new_width = target_width
        new_height = int(orig_height * (target_width / orig_width))

    # Zuerst skalieren
    img = img.resize((new_width, new_height), Image.LANCZOS)

    # Dann zentriert zuschneiden
    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

# Referenzbild für ein 720p-Video im Querformat vorbereiten
processed = center_crop_for_sora("my_photo.jpg", 1280, 720)

Lösung 3: Batch-Verarbeitung über die FFmpeg-Kommandozeile

Für Szenarien, in denen eine große Anzahl von Bildern verarbeitet werden muss, ist FFmpeg die effizientere Wahl:

Modus: Zentriertes Zuschneiden (Cover):

# Zuerst proportional skalieren, dann zentriert auf Zielgröße zuschneiden
ffmpeg -i input.jpg -vf "scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720" output_sora.jpg

Modus: Auffüllen (Letterbox):

# Original-Proportionen beibehalten, fehlende Bereiche schwarz auffüllen
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

Batch-Skript:

#!/bin/bash
# Alle jpg-Bilder im aktuellen Verzeichnis für das Sora 2 API 720p Querformat verarbeiten

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

Lösung 4: Verwendung des Parameters crop_bounds (API-internes Zuschneiden)

Die Sora 2 API bietet den Parameter crop_bounds, mit dem der Zuschneidebereich direkt auf API-Ebene festgelegt werden kann:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Einheitliche APIYI Schnittstelle nutzen
)

# crop_bounds verwenden, um den Zuschneidebereich (als Anteile) festzulegen
with open("full_size_image.jpg", "rb") as f:
    response = client.videos.create(
        model="sora-2",
        prompt="Dynamischer Videoeffekt",
        size="1280x720",
        input_reference=f,
        crop_bounds={
            "left_fraction": 0.1,    # 10% links abschneiden
            "top_fraction": 0.1,     # 10% oben abschneiden
            "right_fraction": 0.9,   # Rechts bis 90% beibehalten
            "bottom_fraction": 0.9   # Unten bis 90% beibehalten
        },
        frame_index=0  # Bild als ersten Frame verwenden
    )

⚠️ Hinweis: Bei Verwendung von crop_bounds muss der resultierende Bereich weiterhin mit der Zielauflösung des Videos korrespondieren. Es wird empfohlen, dies mit einer vorherigen Bildbearbeitung zu kombinieren.

Lösung 5: Vollständige Hilfsklasse zur Bildvorverarbeitung

Hier ist eine produktionsreife Hilfsklasse zur Bildvorverarbeitung, die verschiedene Modi unterstützt:

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

class SoraImagePreprocessor:
    """Vorverarbeitungstool für Sora 2 API Referenzbilder"""

    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"Nicht unterstützte Auflösung: {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def pad(self, image_path, bg_color=(0, 0, 0)):
        """Modus Auffüllen: Originalverhältnis beibehalten, Hintergrundfarbe hinzufügen"""
        img = Image.open(image_path)
        return ImageOps.pad(img, self.target_size, color=bg_color)

    def cover(self, image_path):
        """Modus Abdecken: Originalverhältnis beibehalten, zentriert zuschneiden"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def stretch(self, image_path):
        """Modus Strecken: Erzwungenes Strecken auf Zielgröße (nicht empfohlen)"""
        img = Image.open(image_path)
        return img.resize(self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """PIL-Bild in Byte-Stream für API-Upload umwandeln"""
        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):
        """Bild verarbeiten und speichern"""
        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"Nicht unterstützter Modus: {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

# Anwendungsbeispiel
preprocessor = SoraImagePreprocessor("1280x720")

# Methode 1: Verarbeiten und Speichern
output = preprocessor.process_and_save("my_image.jpg", mode="cover")
print(f"Verarbeitung abgeschlossen: {output}")

# Methode 2: Direkt Byte-Stream für API-Aufruf erhalten
img = preprocessor.cover("my_image.jpg")
image_bytes = preprocessor.to_bytes(img)

import openai
from PIL import Image, ImageOps
import io

class SoraImagePreprocessor:
    """Vorverarbeitungstool für Sora 2 API Referenzbilder"""

    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"Nicht unterstützte Auflösung: {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def cover(self, image_path):
        """Modus Abdecken: Originalverhältnis beibehalten, zentriert zuschneiden"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """PIL-Bild in Byte-Stream umwandeln"""
        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"):
    """
    Sora 2 Video mit vorverarbeitetem Bild generieren

    Args:
        image_path: Pfad zum Originalbild
        prompt: Eingabeaufforderung für die Videobeschreibung
        resolution: Zielauflösung

    Returns:
        ID des Videogenerierungs-Tasks
    """
    # 1. Bild vorverarbeiten
    preprocessor = SoraImagePreprocessor(resolution)
    processed_img = preprocessor.cover(image_path)
    image_bytes = preprocessor.to_bytes(processed_img)

    # 2. Client initialisieren - über die einheitliche Schnittstelle von APIYI
    client = openai.OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    # 3. Sora 2 API aufrufen
    response = client.videos.create(
        model="sora-2",
        prompt=prompt,
        size=resolution,
        input_reference=image_bytes,
        duration=5  # Videodauer in Sekunden
    )

    return response


# Vollständiges Anwendungsbeispiel
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"Videogenerierungs-Task eingereicht: {result}")

Sora 2 API: Vergleich der Bild-Preprocessing-Modi

Die Wahl des richtigen Preprocessing-Modus ist entscheidend für die Qualität des resultierenden Videos:

💡 Auswahlempfehlung: Welcher Preprocessing-Modus am besten geeignet ist, hängt primär von Ihrem Bildinhalt und dem gewünschten Endergebnis ab. Wir empfehlen, praktische Tests über die Plattform APIYI (apiyi.com) durchzuführen, um die Unterschiede der Modi schnell zu validieren.

Empfohlene Modi für verschiedene Szenarien

Sora 2 API Referenzbilder: Häufig gestellte Fragen (FAQ)

# Hochwertige Verarbeitungseinstellungen
img = img.resize(target_size, Image.LANCZOS)  # Lanczos-Algorithmus verwenden
img.save(output_path, "JPEG", quality=95)     # Mit hoher Qualität speichern

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

Sora 2 API Bildgrößen-Referenztabelle

Zur schnellen Orientierung finden Sie hier die vollständige Tabelle zur Größenanpassung:

📌 Hinweis: Zu den verfügbaren Plattformen gehören APIYI (apiyi.com), die offizielle OpenAI API usw. Es wird empfohlen, für Entwicklungstests eine Plattform mit schnellen Reaktionszeiten und günstigen Preisen zu wählen.

Zusammenfassung

Fehlermeldungen zu den Abmessungen des Referenzbildes (Image Prompt) gehören zu den häufigsten Problemen, auf die Entwickler bei der Sora 2 API stoßen. Der Kern der Lösung liegt in folgenden Schritten:

1. Regeln verstehen: Das Referenzbild muss pixelgenau mit den Abmessungen des Zielvideos übereinstimmen.
2. Modus wählen: Wählen Sie je nach Bildinhalt den Modus „Pad“ oder „Cover“.
3. Vorverarbeitung: Nutzen Sie Python Pillow oder FFmpeg für die Vorverarbeitung.
4. Abmessungen validieren: Überprüfen Sie nach der Bearbeitung, ob die Bildgröße tatsächlich übereinstimmt.

Wir empfehlen die Nutzung von APIYI apiyi.com, um die Ergebnisse der Bildvorverarbeitung und die Qualität der Videogenerierung schnell zu überprüfen.

Autor: APIYI Team | Weitere Tipps zur KI-Entwicklung finden Sie unter apiyi.com

Referenzen:

1. OpenAI Sora API Dokumentation: Erläuterungen zur Image-to-Video-Schnittstelle
   • Link: platform.openai.com/docs/guides/video-generation
2. Offizielle Pillow-Dokumentation: ImageOps-Modul zur Bildbearbeitung
   • Link: pillow.readthedocs.io/en/stable/reference/ImageOps.html
3. Offizielle FFmpeg-Dokumentation: Filter für die Video- und Bildverarbeitung
   • Link: ffmpeg.org/ffmpeg-filters.html