5 Cara Mengatasi Kesalahan Ukuran Gambar Inpaint Sora 2 API: Panduan Troubleshooting Lengkap Inpaint image must match

Saat menggunakan Sora 2 API untuk fitur Image-to-Video (gambar ke video), ketidakcocokan ukuran gambar referensi (墊圖) adalah salah satu error yang paling sering ditemui pengembang. Artikel ini akan mengupas tuntas akar penyebab error Inpaint image must match the requested width and height dan memberikan 5 solusi yang telah teruji.

Nilai Inti: Setelah membaca artikel ini, Anda akan memahami aturan validasi ukuran gambar referensi Sora 2 API, mempelajari cara menggunakan Python Pillow dan FFmpeg untuk pra-pemrosesan gambar, serta menyelesaikan masalah error ukuran sepenuhnya.

Analisis Penyebab Error Ukuran Gambar Referensi Sora 2 API

Saat Anda memanggil fungsi Image-to-Video pada Sora 2 API, jika muncul pesan error berikut:

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

Ini berarti ukuran gambar referensi (input_reference) yang Anda unggah tidak sesuai dengan resolusi video target.

Aturan Wajib Pencocokan Ukuran Sora 2 API

Sora 2 API memiliki mekanisme validasi ukuran yang ketat:

Resolusi Video yang Didukung Sora 2 API

Berdasarkan dokumentasi resmi OpenAI, Sora 2 API saat ini mendukung resolusi berikut:

🎯 Penting: Gambar referensi Anda harus sama persis secara piksel dengan resolusi target yang dipilih. Misalnya, jika memilih resolusi 1280×720, maka gambar referensi harus berukuran tepat 1280×720 piksel. Selisih 1 piksel saja akan menyebabkan error.

5 Solusi untuk Galat Ukuran Gambar Referensi Sora 2 API

Solusi 1: Padding dan Pemotongan Cerdas Python Pillow

Menggunakan metode ImageOps.pad() dari Pillow memungkinkan pemrosesan gambar dengan ukuran apa pun secara cerdas, menjaga rasio aspek sambil mengisi (padding) ke ukuran target:

from PIL import Image, ImageOps
import openai

# Resolusi standar yang didukung oleh Sora 2 API
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"):
    """Pra-pemrosesan gambar untuk memenuhi persyaratan ukuran Sora 2 API"""
    target_size = SORA_RESOLUTIONS[target_resolution]

    # Buka gambar asli
    img = Image.open(image_path)

    # Gunakan metode pad: pertahankan rasio aspek, isi latar belakang dengan warna hitam
    processed = ImageOps.pad(img, target_size, color=(0, 0, 0))

    # Simpan gambar yang telah diproses
    output_path = image_path.replace(".jpg", "_sora_ready.jpg")
    processed.save(output_path, "JPEG", quality=95)

    return output_path

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

# Panggil Sora 2 API - Melalui antarmuka terpadu APIYI
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Menggunakan antarmuka terpadu 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
    )

🚀 Mulai Cepat: Direkomendasikan menggunakan platform APIYI (apiyi.com) untuk menguji Sora 2 API dengan cepat. Platform ini menyediakan antarmuka yang siap pakai, memungkinkan integrasi tanpa konfigurasi yang rumit.

Solusi 2: Center Crop Python Pillow (Mempertahankan Subjek Utama)

Jika Anda ingin mempertahankan konten utama gambar tanpa isian bar hitam (letterbox), Anda bisa menggunakan pemotongan tengah (center crop):

from PIL import Image

def center_crop_for_sora(image_path, target_width, target_height):
    """Memotong gambar di tengah untuk menyesuaikan dengan persyaratan ukuran Sora 2 API"""
    img = Image.open(image_path)
    orig_width, orig_height = img.size

    # Hitung rasio aspek target
    target_ratio = target_width / target_height
    orig_ratio = orig_width / orig_height

    if orig_ratio > target_ratio:
        # Gambar asli lebih lebar, skala berdasarkan tinggi lalu potong kedua sisi
        new_height = target_height
        new_width = int(orig_width * (target_height / orig_height))
    else:
        # Gambar asli lebih tinggi, skala berdasarkan lebar lalu potong atas dan bawah
        new_width = target_width
        new_height = int(orig_height * (target_width / orig_width))

    # Skala terlebih dahulu
    img = img.resize((new_width, new_height), Image.LANCZOS)

    # Kemudian potong di tengah
    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

# Menyiapkan gambar referensi untuk video 720p landscape
processed = center_crop_for_sora("my_photo.jpg", 1280, 720)

Solusi 3: Pemrosesan Batch Baris Perintah FFmpeg

Untuk skenario yang membutuhkan pemrosesan massal, FFmpeg adalah pilihan yang lebih efisien:

Mode Center Crop (Cover):

# Skala dulu dengan mempertahankan rasio, lalu potong di tengah ke ukuran target
ffmpeg -i input.jpg -vf "scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720" output_sora.jpg

Mode Padding (Letterbox):

# Pertahankan rasio asli saat skala, bagian yang kurang diisi dengan warna hitam
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

Skrip Pemrosesan Batch:

#!/bin/bash
# Memproses semua gambar jpg di direktori saat ini ke format landscape 720p Sora 2 API secara massal

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

Solusi 4: Menggunakan Parameter crop_bounds (Pemotongan Bawaan API)

Sora 2 API menyediakan parameter crop_bounds, yang memungkinkan penentuan area pemotongan langsung di level API:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Menggunakan antarmuka terpadu APIYI
)

# Gunakan crop_bounds untuk menentukan area pemotongan (dalam bentuk rasio)
with open("full_size_image.jpg", "rb") as f:
    response = client.videos.create(
        model="sora-2",
        prompt="Efek video dinamis",
        size="1280x720",
        input_reference=f,
        crop_bounds={
            "left_fraction": 0.1,    # Potong 10% dari kiri
            "top_fraction": 0.1,     # Potong 10% dari atas
            "right_fraction": 0.9,   # Pertahankan hingga 90% di kanan
            "bottom_fraction": 0.9   # Pertahankan hingga 90% di bawah
        },
        frame_index=0  # Gambar sebagai frame pertama
    )

⚠️ Catatan: Saat menggunakan crop_bounds, area yang telah dipotong harus tetap sesuai dengan resolusi video target. Disarankan untuk mengombinasikannya dengan pra-pemrosesan awal.

Solusi 5: Kelas Utilitas Pra-pemrosesan Gambar yang Lengkap

Berikut adalah kelas utilitas pra-pemrosesan gambar tingkat produksi yang mencakup berbagai mode pemrosesan:

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

class SoraImagePreprocessor:
    """Alat pra-pemrosesan gambar referensi Sora 2 API"""

    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"Resolusi tidak didukung: {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def pad(self, image_path, bg_color=(0, 0, 0)):
        """Mode Padding: Pertahankan rasio asli, tambahkan warna latar belakang"""
        img = Image.open(image_path)
        return ImageOps.pad(img, self.target_size, color=bg_color)

    def cover(self, image_path):
        """Mode Cover: Pertahankan rasio asli, potong di tengah"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def stretch(self, image_path):
        """Mode Stretch: Paksa regangkan ke ukuran target (tidak direkomendasikan)"""
        img = Image.open(image_path)
        return img.resize(self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """Mengonversi PIL Image menjadi aliran byte untuk unggahan 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):
        """Memproses dan menyimpan gambar"""
        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 tidak didukung: {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

# Contoh penggunaan
preprocessor = SoraImagePreprocessor("1280x720")

# Cara 1: Proses dan simpan
output = preprocessor.process_and_save("my_image.jpg", mode="cover")
print(f"Proses selesai: {output}")

# Cara 2: Dapatkan aliran byte langsung untuk pemanggilan API
img = preprocessor.cover("my_image.jpg")
image_bytes = preprocessor.to_bytes(img)

import openai
from PIL import Image, ImageOps
import io

class SoraImagePreprocessor:
    """Alat pra-pemrosesan gambar referensi Sora 2 API"""

    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"Resolusi tidak didukung: {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def cover(self, image_path):
        """Mode Cover: Pertahankan rasio asli, potong di tengah"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """Mengonversi PIL Image menjadi aliran byte"""
        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"):
    """
    Menghasilkan video Sora 2 menggunakan gambar yang telah diproses sebelumnya

    Args:
        image_path: Jalur gambar asli
        prompt: Petunjuk deskripsi video
        resolution: Resolusi target

    Returns:
        ID tugas pembuatan video
    """
    # 1. Pra-pemrosesan gambar
    preprocessor = SoraImagePreprocessor(resolution)
    processed_img = preprocessor.cover(image_path)
    image_bytes = preprocessor.to_bytes(processed_img)

    # 2. Inisialisasi klien - Melalui antarmuka terpadu APIYI
    client = openai.OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    # 3. Panggil Sora 2 API
    response = client.videos.create(
        model="sora-2",
        prompt=prompt,
        size=resolution,
        input_reference=image_bytes,
        duration=5  # Durasi video (detik)
    )

    return response


# Contoh pemanggilan lengkap
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"Tugas pembuatan video telah dikirim: {result}")

Perbandingan Mode Pra-pemrosesan Gambar Referensi Sora 2 API

Memilih mode pra-pemrosesan yang tepat sangat penting untuk hasil video:

💡 Saran Pemilihan: Mode pra-pemrosesan mana yang dipilih sangat bergantung pada konten gambar Anda dan kebutuhan hasil akhir. Kami menyarankan untuk melakukan pengujian nyata melalui platform APIYI (apiyi.com) untuk memvalidasi perbedaan efek dari berbagai mode dengan cepat.

Mode Rekomendasi untuk Berbagai Skenario

Pertanyaan Umum seputar Image Padding Sora 2 API

# Pengaturan pemrosesan kualitas tinggi
img = img.resize(target_size, Image.LANCZOS)  # Menggunakan algoritma Lanczos
img.save(output_path, "JPEG", quality=95)     # Simpan dengan kualitas tinggi

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

Tabel Referensi Cepat Ukuran Image Padding Sora 2 API

Untuk memudahkan pengecekan cepat, berikut adalah tabel lengkap kecocokan ukuran:

📌 Petunjuk: Platform yang tersedia meliputi APIYI apiyi.com, API resmi OpenAI, dll. Disarankan untuk memilih platform dengan kecepatan respons yang cepat dan harga yang kompetitif untuk pengembangan dan pengujian.

Kesimpulan

Kesalahan ukuran gambar referensi (padding) pada Sora 2 API adalah salah satu masalah yang paling sering dihadapi pengembang. Strategi penyelesaian utamanya adalah:

1. Pahami Aturan: Gambar referensi harus memiliki ukuran piksel yang sama persis dengan video target.
2. Pilih Mode: Pilih mode Pad atau Cover berdasarkan konten gambar.
3. Pra-pemrosesan: Gunakan Python Pillow atau FFmpeg untuk melakukan pemrosesan awal.
4. Verifikasi Ukuran: Pastikan ukuran gambar sudah sesuai setelah diproses.

Direkomendasikan menggunakan APIYI apiyi.com untuk memverifikasi efek pra-pemrosesan gambar dan kualitas pembuatan video dengan cepat.

Penulis: APIYI Team | Kunjungi apiyi.com untuk lebih banyak tips pengembangan AI.

Referensi:

1. Dokumentasi OpenAI Sora API: Penjelasan antarmuka Image-to-Video
   • Tautan: platform.openai.com/docs/guides/video-generation
2. Dokumentasi Resmi Pillow: Modul pemrosesan gambar ImageOps
   • Tautan: pillow.readthedocs.io/en/stable/reference/ImageOps.html
3. Dokumentasi Resmi FFmpeg: Filter pemrosesan video dan gambar
   • Tautan: ffmpeg.org/ffmpeg-filters.html