5 métodos para resolver o erro de tamanho da imagem da API Sora 2: Guia completo para Inpaint image must match

Ao utilizar a API Sora 2 para gerar vídeos a partir de imagens (Image-to-Video), a incompatibilidade do tamanho da imagem de referência é um dos erros mais comuns enfrentados pelos desenvolvedores. Este artigo analisará detalhadamente a causa raiz do erro Inpaint image must match the requested width and height e fornecerá 5 soluções comprovadas.

Valor central: Ao terminar de ler este artigo, você dominará as regras de validação de tamanho de imagem da API Sora 2, aprenderá a usar Python Pillow e FFmpeg para pré-processar imagens e resolverá definitivamente os erros de dimensão.

Análise da causa do erro de tamanho de imagem na API Sora 2

Ao chamar a função de imagem para vídeo da API Sora 2, se você visualizar a seguinte mensagem de erro:

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

Isso significa que as dimensões da imagem de referência enviada (input_reference) não correspondem à resolução do vídeo de destino.

Regras rígidas de correspondência de tamanho da API Sora 2

A API Sora 2 possui um mecanismo rigoroso de validação de dimensões para imagens de referência:

Resoluções de vídeo suportadas pela API Sora 2

De acordo com a documentação oficial da OpenAI, a API Sora 2 suporta atualmente as seguintes resoluções:

🎯 Dica Importante: Sua imagem de referência deve ser exatamente igual em pixels à resolução de destino escolhida. Por exemplo, se selecionar 1280×720, a imagem deve ter exatamente 1280×720 pixels; uma diferença de apenas 1 pixel causará erro.

5 soluções para o erro de tamanho da imagem de referência na API do Sora 2

Solução 1: Preenchimento inteligente com Python Pillow

O uso do método ImageOps.pad() do Pillow permite processar de forma inteligente imagens de qualquer tamanho, mantendo a proporção original enquanto preenche o espaço restante para atingir o tamanho de destino:

from PIL import Image, ImageOps
import openai

# 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"):
    """预处理图片以匹配 Sora 2 API 尺寸要求"""
    target_size = SORA_RESOLUTIONS[target_resolution]

    # 打开原图
    img = Image.open(image_path)

    # 使用 pad 方法：保持宽高比，填充黑色背景
    processed = ImageOps.pad(img, target_size, color=(0, 0, 0))

    # 保存处理后的图片
    output_path = image_path.replace(".jpg", "_sora_ready.jpg")
    processed.save(output_path, "JPEG", quality=95)

    return output_path

# 使用示例
processed_image = preprocess_image_for_sora("my_image.jpg", "landscape_720p")

# 调用 Sora 2 API - 通过 APIYI 统一接口
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 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
    )

🚀 Início rápido: Recomendamos usar a plataforma APIYI (apiyi.com) para testar rapidamente a API do Sora 2. A plataforma oferece interfaces prontas para uso, permitindo a integração sem a necessidade de configurações complexas.

Solução 2: Recorte centralizado com Pillow (Mantendo o assunto principal)

Se você deseja manter o conteúdo principal da imagem e evitar as bordas pretas de preenchimento, pode utilizar o recorte centralizado:

from PIL import Image

def center_crop_for_sora(image_path, target_width, target_height):
    """居中裁剪图片以匹配 Sora 2 API 尺寸要求"""
    img = Image.open(image_path)
    orig_width, orig_height = img.size

    # 计算目标宽高比
    target_ratio = target_width / target_height
    orig_ratio = orig_width / orig_height

    if orig_ratio > target_ratio:
        # 原图更宽，按高度缩放后裁剪两边
        new_height = target_height
        new_width = int(orig_width * (target_height / orig_height))
    else:
        # 原图更高，按宽度缩放后裁剪上下
        new_width = target_width
        new_height = int(orig_height * (target_width / orig_width))

    # 先缩放
    img = img.resize((new_width, new_height), Image.LANCZOS)

    # 再居中裁剪
    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

# 为横屏 720p 视频准备垫图
processed = center_crop_for_sora("my_photo.jpg", 1280, 720)

Solução 3: Processamento em lote com linha de comando FFmpeg

Para cenários que exigem processamento em lote, o FFmpeg é uma escolha mais eficiente:

Modo de recorte centralizado (Cover):

# 先缩放保持比例，再居中裁剪到目标尺寸
ffmpeg -i input.jpg -vf "scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720" output_sora.jpg

Modo de preenchimento (Letterbox):

# 保持原比例缩放，不足部分填充黑色
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 processamento em lote:

#!/bin/bash
# 批量处理当前目录所有 jpg 图片为 Sora 2 API 720p 横屏格式

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

Solução 4: Uso do parâmetro crop_bounds (Recorte integrado na API)

A API do Sora 2 oferece o parâmetro crop_bounds, que permite especificar a área de recorte diretamente na chamada da API:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 APIYI 统一接口
)

# 使用 crop_bounds 指定裁剪区域（以比例形式）
with open("full_size_image.jpg", "rb") as f:
    response = client.videos.create(
        model="sora-2",
        prompt="动态视频效果",
        size="1280x720",
        input_reference=f,
        crop_bounds={
            "left_fraction": 0.1,    # 左边裁掉 10%
            "top_fraction": 0.1,     # 顶部裁掉 10%
            "right_fraction": 0.9,   # 右边保留到 90%
            "bottom_fraction": 0.9   # 底部保留到 90%
        },
        frame_index=0  # 图片作为第一帧
    )

⚠️ Atenção: Ao usar o crop_bounds, a área recortada ainda deve ser compatível com a resolução final do vídeo. Recomenda-se combinar esta técnica com um pré-processamento inicial.

Solução 5: Classe utilitária completa para pré-processamento de imagem

Abaixo está uma classe utilitária de pré-processamento de imagem de nível de produção, que inclui diversos modos de tratamento:

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

class SoraImagePreprocessor:
    """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"不支持的分辨率: {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def pad(self, image_path, bg_color=(0, 0, 0)):
        """填充模式：保持原图比例，添加背景色填充"""
        img = Image.open(image_path)
        return ImageOps.pad(img, self.target_size, color=bg_color)

    def cover(self, image_path):
        """覆盖模式：保持原图比例，居中裁剪"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def stretch(self, image_path):
        """拉伸模式：强制拉伸到目标尺寸（不推荐）"""
        img = Image.open(image_path)
        return img.resize(self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """将 PIL Image 转换为字节流，用于 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):
        """处理并保存图片"""
        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}")

        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

# 使用示例
preprocessor = SoraImagePreprocessor("1280x720")

# 方式1：处理并保存
output = preprocessor.process_and_save("my_image.jpg", mode="cover")
print(f"处理完成: {output}")

# 方式2：直接获取字节流用于 API 调用
img = preprocessor.cover("my_image.jpg")
image_bytes = preprocessor.to_bytes(img)

import openai
from PIL import Image, ImageOps
import io

class SoraImagePreprocessor:
    """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"不支持的分辨率: {target_resolution}")
        self.target_size = self.RESOLUTIONS[target_resolution]

    def cover(self, image_path):
        """覆盖模式：保持原图比例，居中裁剪"""
        img = Image.open(image_path)
        return ImageOps.fit(img, self.target_size, Image.LANCZOS)

    def to_bytes(self, img, format="JPEG", quality=95):
        """将 PIL Image 转换为字节流"""
        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"):
    """
    使用预处理后的图片 generate Sora 2 视频

    Args:
        image_path: 原始图片路径
        prompt: 视频描述提示词
        resolution: 目标分辨率

    Returns:
        视频生成任务 ID
    """
    # 1. 预处理图片
    preprocessor = SoraImagePreprocessor(resolution)
    processed_img = preprocessor.cover(image_path)
    image_bytes = preprocessor.to_bytes(processed_img)

    # 2. 初始化客户端 - 通过 APIYI 统一接口
    client = openai.OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.apiyi.com/v1"
    )

    # 3. 调用 Sora 2 API
    response = client.videos.create(
        model="sora-2",
        prompt=prompt,
        size=resolution,
        input_reference=image_bytes,
        duration=5  # 视频时长（秒）
    )

    return response


# 完整调用示例
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"视频生成任务已提交: {result}")

Comparação de Modos de Pré-processamento de Imagem de Referência da API Sora 2

Escolher o modo de pré-processamento adequado é fundamental para o resultado final do vídeo:

💡 Sugestão de escolha: O modo de pré-processamento ideal depende principalmente do conteúdo da sua imagem e do efeito final desejado. Recomendamos realizar testes práticos através da plataforma APIYI (apiyi.com) para validar rapidamente as diferenças de resultado entre os modos.

Modos Recomendados por Cenário

Perguntas Frequentes sobre Imagens de Referência na API do Sora 2

# Configurações de processamento de alta qualidade
img = img.resize(target_size, Image.LANCZOS)  # Usando o algoritmo Lanczos
img.save(output_path, "JPEG", quality=95)     # Salvando com alta qualidade

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

Tabela de Referência Rápida: Tamanhos para API do Sora 2

Para facilitar sua consulta, aqui está a tabela completa de correspondência de tamanhos:

📌 Dica: As plataformas disponíveis incluem APIYI (apiyi.com) e a API oficial da OpenAI. Recomendamos escolher plataformas com alta velocidade de resposta e preços competitivos para o seu desenvolvimento e testes.

Resumo

O erro de dimensão de imagem de referência na API do Sora 2 é um dos problemas mais comuns enfrentados pelos desenvolvedores. A lógica principal para resolvê-lo é:

1. Entender a regra: A imagem de referência deve ter exatamente as mesmas dimensões em pixels que o vídeo de destino.
2. Escolher o modo: Selecione o modo Pad ou Cover de acordo com o conteúdo da imagem.
3. Pré-processamento: Utilize Python Pillow ou FFmpeg para o pré-processamento.
4. Validar dimensões: Após o processamento, verifique se as dimensões da imagem coincidem.

Recomendamos utilizar o APIYI (apiyi.com) para validar rapidamente os resultados do pré-processamento de imagens e a qualidade da geração de vídeos.

Autor: Equipe APIYI | Para mais dicas de desenvolvimento de IA, visite apiyi.com

Referências:

1. Documentação da API do OpenAI Sora: Instruções da interface de Imagem-para-Vídeo
   • Link: platform.openai.com/docs/guides/video-generation
2. Documentação oficial do Pillow: Módulo de processamento de imagem ImageOps
   • Link: pillow.readthedocs.io/en/stable/reference/ImageOps.html
3. Documentação oficial do FFmpeg: Filtros de processamento de vídeo e imagem
   • Link: ffmpeg.org/ffmpeg-filters.html