3 حلول لإصلاح خطأ مدة فيديو Sora 2 API: خطأ invalid_value في معامل seconds

عند استدعاء Sora 2 API لإنشاء فيديو، إذا تم تمرير قيمة غير مدعومة للمعلمة seconds (الثواني)، فسيتم إرجاع خطأ invalid_value على الفور. سنحلل في هذا المقال بالتفصيل السبب الجذري للخطأ Invalid value: '10'. Supported values are: '4', '8', and '12' ونقدم حلاً كاملاً للإصلاح.

القيمة الجوهرية: بعد قراءة هذا المقال، ستتقن الفروق في معلمات المدة بين إصدار Sora 2 القياسي وإصدار Pro، وتتعلم كيفية ضبط معلمة seconds بشكل صحيح لتجنب رفض طلبات إنشاء الفيديو.

تحليل أسباب خطأ المعلمة seconds في Sora 2 API

عند استدعاء Sora 2 API، إذا ظهرت لك رسالة الخطأ التالية:

{
  "message": "Invalid value: '10'. Supported values are: '4', '8', and '12'.",
  "data": {
    "error": {
      "code": "invalid_value",
      "message": "Invalid value: '10'. Supported values are: '4', '8', and '12'.",
      "param": "seconds",
      "type": "invalid_request_error"
    }
  }
}

فهذا يشير إلى أن قيمة المعلمة seconds التي أدخلتها (في هذا المثال هي 10) ليست ضمن النطاق المسموح به في واجهة البرمجة (API).

آلية التحقق الصارمة لمعلمات المدة في Sora 2 API

تعتمد Sora 2 API آلية تحقق من القيم الثابتة لمدد الفيديو، ولا تدعم أي عدد عشوائي من الثواني:

لماذا تقيد Sora 2 API مدة الفيديو بقيم ثابتة؟

في الإصدار التجريبي من Sora 2، قامت OpenAI بتعمد تقييد قيم المدة المتاحة للأسباب التالية:

1. تحسين موارد الحوسبة: تسهل المدد الثابتة التخصيص المسبق لموارد وحدة معالجة الرسومات (GPU).
2. اتساق الجودة: تم تحسين المدد المحددة مسبقاً لضمان نتائج إنشاء أكثر استقراراً وجودة.
3. التحكم في التكاليف: يساعد تقييد الطول في تجنب تكبد المستخدمين لرسوم عالية غير متوقعة.
4. خصائص النموذج: يحقق Sora 2 أفضل اتساق بين الإطارات في مدد زمنية محددة.

🎯 ملاحظة هامة: قيم المدة التي يدعمها إصدار Sora 2 القياسي وإصدار Pro مختلفة تماماً، ويجب عليك اختيار قيمة المعلمة الصحيحة بناءً على النموذج المستخدم.

مقارنة معلمات المدة بين إصداري Sora 2 القياسي وPro

هذا هو السبب الأكثر شيوعاً للأخطاء: الخلط بين معلمات الإصدار القياسي وإصدار Pro.

المدد التي يدعمها إصدار Sora 2 القياسي (sora-2)

المدد التي يدعمها إصدار Sora 2 Pro (sora-2-pro)

جدول مقارنة المعلمات الكامل

💡 نصيحة الاختيار: إذا كنت بحاجة إلى فيديو مدته 10 ثوانٍ، يجب عليك استخدام نموذج sora-2-pro بدلاً من sora-2. ننصح باختبار مجموعات مختلفة من النماذج والمدد عبر منصة APIYI apiyi.com للعثور بسرعة على التكوين الأنسب لاحتياجاتك.

3 حلول لإصلاح خطأ "seconds" في واجهة برمجة تطبيقات Sora 2 (Sora 2 API)

الحل الأول: استخدام القيمة الصحيحة للثواني (النسخة القياسية – Standard)

إذا كنت تستخدم نموذج sora-2 القياسي، فيجب عليك استخدام 4 أو 8 أو 12 ثانية فقط:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # استخدام واجهة APIYI الموحدة
)

# ✅ صحيح: استخدام قيم المدة التي تدعمها النسخة القياسية
response = client.videos.create(
    model="sora-2",           # نموذج النسخة القياسية
    prompt="A cat playing with a ball in a sunny garden",
    seconds=8,                # يمكن أن تكون فقط 4، 8، أو 12
    size="1280x720"
)

print(f"مهمة توليد الفيديو: {response.id}")

🚀 ابدأ بسرعة: نوصي باستخدام منصة APIYI (apiyi.com) لاختبار Sora 2 API بسرعة، حيث توفر المنصة واجهة جاهزة للاستخدام وتدعم التبديل بين نماذج النسخة القياسية والنسخة الاحترافية (Pro).

الحل الثاني: التبديل إلى نسخة Pro للحصول على مدة أطول

إذا كنت بحاجة إلى مقاطع فيديو مدتها 10 أو 15 أو 25 ثانية، فيجب عليك التبديل إلى نموذج sora-2-pro:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # استخدام واجهة APIYI الموحدة
)

# ✅ صحيح: استخدام نسخة Pro للحصول على مدة أطول
response = client.videos.create(
    model="sora-2-pro",       # نموذج نسخة Pro
    prompt="A cinematic sunrise over mountains with birds flying",
    seconds=15,               # تدعم نسخة Pro القيم 10، 15، 25
    size="1792x1024"          # تدعم نسخة Pro دقة أعلى
)

print(f"مهمة توليد الفيديو: {response.id}")

الحل الثالث: تنفيذ فئة برمجية (Class) ذكية لملاءمة المدة تلقائياً

فيما يلي أداة مهايئة لمعلمات المدة بمستوى احترافي، تعالج تلقائياً التوافق بين النموذج والمدة المطلوبة:

import openai
from typing import Literal, Optional

class SoraVideoGenerator:
    """أداة توليد فيديو Sora 2 API، تقوم بملاءمة معلمات المدة تلقائياً"""

    # إعدادات المدة التي يدعمها النموذج
    MODEL_DURATIONS = {
        "sora-2": {
            "supported": [4, 8, 12],
            "default": 4,
            "max_resolution": "1280x720"
        },
        "sora-2-pro": {
            "supported": [10, 15, 25],
            "default": 10,
            "max_resolution": "1792x1024"
        }
    }

    def __init__(self, api_key: str, base_url: str = "https://api.apiyi.com/v1"):
        self.client = openai.OpenAI(api_key=api_key, base_url=base_url)

    def get_valid_duration(self, model: str, desired_seconds: int) -> int:
        """الحصول على أقرب مدة صالحة للقيمة المطلوبة"""
        if model not in self.MODEL_DURATIONS:
            raise ValueError(f"نموذج غير مدعوم: {model}")

        supported = self.MODEL_DURATIONS[model]["supported"]

        # إذا كانت القيمة المطلوبة صالحة، يتم إرجاعها مباشرة
        if desired_seconds in supported:
            return desired_seconds

        # بخلاف ذلك، يتم إرجاع أقرب قيمة صالحة
        closest = min(supported, key=lambda x: abs(x - desired_seconds))
        print(f"⚠️ المدة {desired_seconds} ثانية غير مدعومة، تم تعديلها تلقائياً إلى {closest} ثانية")
        return closest

    def suggest_model(self, desired_seconds: int) -> str:
        """التوصية بالنموذج المناسب بناءً على المدة المطلوبة"""
        if desired_seconds <= 12:
            return "sora-2"
        else:
            return "sora-2-pro"

    def create_video(
        self,
        prompt: str,
        seconds: int,
        model: Optional[str] = None,
        size: Optional[str] = None,
        auto_adjust: bool = True
    ):
        """
        إنشاء فيديو، يدعم التعديل التلقائي للمعلمات

        Args:
            prompt: وصف الفيديو (الموجه)
            seconds: المدة المطلوبة
            model: اسم النموذج، سيتم الاختيار تلقائياً إذا لم يتم تحديده
            size: الدقة
            auto_adjust: ما إذا كان سيتم تعديل المعلمات غير المدعومة تلقائياً
        """
        # اختيار النموذج تلقائياً
        if model is None:
            model = self.suggest_model(seconds)
            print(f"📌 اختيار النموذج تلقائياً: {model}")

        # التحقق من المدة وتعديلها
        if auto_adjust:
            seconds = self.get_valid_duration(model, seconds)
        elif seconds not in self.MODEL_DURATIONS[model]["supported"]:
            supported = self.MODEL_DURATIONS[model]["supported"]
            raise ValueError(
                f"النموذج {model} لا يدعم {seconds} ثانية، "
                f"القيم المدعومة هي: {supported}"
            )

        # تعيين الدقة الافتراضية
        if size is None:
            size = self.MODEL_DURATIONS[model]["max_resolution"]

        # استدعاء واجهة برمجة التطبيقات (API)
        response = self.client.videos.create(
            model=model,
            prompt=prompt,
            seconds=seconds,
            size=size
        )

        return {
            "task_id": response.id,
            "model": model,
            "seconds": seconds,
            "size": size
        }

# مثال على الاستخدام
generator = SoraVideoGenerator(api_key="YOUR_API_KEY")

# المثال 1: اختيار النموذج وتعديل المدة تلقائياً
result = generator.create_video(
    prompt="Ocean waves crashing on a beach at sunset",
    seconds=10  # سيتم اختيار sora-2-pro تلقائياً
)
print(f"نتيجة التوليد: {result}")

# المثال 2: تحديد النموذج وتعديل المدة تلقائياً
result = generator.create_video(
    prompt="A coffee cup with steam rising",
    seconds=10,          # 10 ثوانٍ غير صالحة لنموذج sora-2
    model="sora-2",      # تحديد النسخة القياسية
    auto_adjust=True     # سيتم التعديل تلقائياً إلى 12 أو 8 ثوانٍ
)
print(f"نتيجة التوليد: {result}")

import openai
import asyncio
from typing import Literal, Optional, Dict, Any
from dataclasses import dataclass
from enum import Enum

class SoraModel(Enum):
    """تعداد نماذج Sora"""
    STANDARD = "sora-2"
    PRO = "sora-2-pro"

@dataclass
class ModelConfig:
    """تكوين النموذج"""
    supported_durations: list[int]
    default_duration: int
    max_resolution: str
    has_audio: bool

class SoraVideoGenerator:
    """
    أداة توليد فيديوهات Sora 2 API

    الميزات:
    - ملاءمة تلقائية لمعلمات المدة
    - اختيار تلقائي للنموذج
    - التحقق من صحة المعلمات
    - آلية إعادة المحاولة
    """

    MODELS: Dict[str, ModelConfig] = {
        "sora-2": ModelConfig(
            supported_durations=[4, 8, 12],
            default_duration=4,
            max_resolution="1280x720",
            has_audio=False
        ),
        "sora-2-pro": ModelConfig(
            supported_durations=[10, 15, 25],
            default_duration=10,
            max_resolution="1792x1024",
            has_audio=True
        )
    }

    RESOLUTIONS = {
        "720p_landscape": "1280x720",
        "720p_portrait": "720x1280",
        "1080p_landscape": "1792x1024",
        "1080p_portrait": "1024x1792",
    }

    def __init__(
        self,
        api_key: str,
        base_url: str = "https://api.apiyi.com/v1",
        max_retries: int = 3
    ):
        self.client = openai.OpenAI(api_key=api_key, base_url=base_url)
        self.max_retries = max_retries

    def validate_model(self, model: str) -> ModelConfig:
        """التحقق من النموذج وإرجاع التكوين"""
        if model not in self.MODELS:
            available = list(self.MODELS.keys())
            raise ValueError(f"نموذج غير مدعوم: {model}، النماذج المتاحة هي: {available}")
        return self.MODELS[model]

    def get_valid_duration(self, model: str, desired: int) -> int:
        """الحصول على أقرب مدة صالحة للقيمة المطلوبة"""
        config = self.validate_model(model)
        supported = config.supported_durations

        if desired in supported:
            return desired

        closest = min(supported, key=lambda x: x if abs(x - desired) == 0 else abs(x - desired))
        # تصحيح منطق اختيار الأقرب
        closest = min(supported, key=lambda x: abs(x - desired))
        return closest

    def suggest_model_for_duration(self, seconds: int) -> str:
        """التوصية بالنموذج المناسب بناءً على المدة المطلوبة"""
        # التحقق مما إذا كانت النسخة القياسية تدعمها
        if seconds in self.MODELS["sora-2"].supported_durations:
            return "sora-2"
        # التحقق مما إذا كانت نسخة Pro تدعمها
        if seconds in self.MODELS["sora-2-pro"].supported_durations:
            return "sora-2-pro"
        # الاختيار الافتراضي بناءً على المدة
        return "sora-2" if seconds <= 12 else "sora-2-pro"

    def create_video(
        self,
        prompt: str,
        seconds: int,
        model: Optional[str] = None,
        size: Optional[str] = None,
        auto_adjust: bool = True
    ) -> Dict[str, Any]:
        """
        إنشاء فيديو

        Args:
            prompt: الموجه الخاص بوصف الفيديو
            seconds: مدة الفيديو المطلوبة (بالثواني)
            model: اسم النموذج، سيتم الاختيار تلقائياً إذا كان None
            size: الدقة، سيتم استخدام القيمة الافتراضية إذا كان None
            auto_adjust: ما إذا كان سيتم تعديل المعلمات غير المدعومة تلقائياً

        Returns:
            قاموس يحتوي على معلومات المهمة

        Raises:
            ValueError: إذا كانت المعلمات غير صالحة و auto_adjust=False
        """
        # اختيار النموذج تلقائياً
        if model is None:
            model = self.suggest_model_for_duration(seconds)

        config = self.validate_model(model)

        # معالجة معلمات المدة
        original_seconds = seconds
        if seconds not in config.supported_durations:
            if auto_adjust:
                seconds = self.get_valid_duration(model, seconds)
                print(f"⚠️ تم تعديل المدة: {original_seconds}ث ← {seconds}ث")
            else:
                raise ValueError(
                    f"النموذج {model} لا يدعم {seconds}ث، "
                    f"القيم المدعومة هي: {config.supported_durations}"
                )

        # تعيين الدقة
        if size is None:
            size = config.max_resolution

        # استدعاء واجهة البرمجة (مع إعادة المحاولة)
        last_error = None
        for attempt in range(self.max_retries):
            try:
                response = self.client.videos.create(
                    model=model,
                    prompt=prompt,
                    seconds=seconds,
                    size=size
                )
                return {
                    "success": True,
                    "task_id": response.id,
                    "model": model,
                    "seconds": seconds,
                    "size": size,
                    "has_audio": config.has_audio,
                    "adjusted": original_seconds != seconds
                }
            except Exception as e:
                last_error = e
                if attempt < self.max_retries - 1:
                    wait_time = 2 ** attempt
                    print(f"⏳ فشل الطلب، سيتم إعادة المحاولة بعد {wait_time} ثانية...")
                    import time
                    time.sleep(wait_time)

        return {
            "success": False,
            "error": str(last_error),
            "model": model,
            "seconds": seconds
        }

    @staticmethod
    def get_duration_info() -> str:
        """الحصول على معلومات المساعدة الخاصة بمعلمات المدة"""
        info = ["توضيح معلمات المدة لـ Sora 2 API:", ""]
        for model, config in SoraVideoGenerator.MODELS.items():
            durations = ", ".join(map(str, config.supported_durations))
            info.append(f"  {model}: {durations} ثانية")
            info.append(f"    الافتراضي: {config.default_duration} ثانية")
            info.append(f"    أقصى دقة: {config.max_resolution}")
            info.append(f"    الصوت: {'مدعوم' if config.has_audio else 'غير مدعوم'}")
            info.append("")
        return "\n".join(info)


# مثال على الاستخدام
if __name__ == "__main__":
    # طباعة معلومات المساعدة
    print(SoraVideoGenerator.get_duration_info())

    # تهيئة المولد
    generator = SoraVideoGenerator(api_key="YOUR_API_KEY")

    # المثال 1: ترك الأداة تختار أفضل تكوين تلقائياً
    result = generator.create_video(
        prompt="A serene lake reflecting autumn trees",
        seconds=10
    )
    print(f"النتيجة: {result}")

    # المثال 2: فرض استخدام نموذج محدد
    result = generator.create_video(
        prompt="Quick product showcase",
        seconds=5,
        model="sora-2",
        auto_adjust=True  # سيتم تعديل الـ 5 ثوانٍ إلى 4 ثوانٍ
    )
    print(f"النتيجة: {result}")

أفضل الممارسات لمعلمة المدة (Duration) في Sora 2 API

اختيار المدة المناسبة حسب السيناريو

العلاقة بين المدة وجودة التوليد

بناءً على توصيات OpenAI الرسمية والخبرة العملية:

💰 تحسين التكلفة: بالنسبة للمشاريع ذات الميزانية المحدودة، نقترح اختبار جودة الموجه بمدة 4 ثوانٍ أولاً، وبمجرد الرضا عن النتيجة، يمكنك توليد النسخة الأطول. يمكنك الحصول على أسعار استدعاء أكثر تفضيلاً من خلال منصة APIYI (apiyi.com).

البدائل المتاحة للفيديوهات الطويلة

إذا كنت بحاجة إلى فيديو تتجاوز مدته 25 ثانية، يمكنك اعتماد الاستراتيجية التالية:

def create_long_video_segments(generator, prompt_segments, model="sora-2"):
    """
    إنشاء خطة توليد مجزأة للفيديوهات الطويلة

    المعاملات:
        generator: كائن من SoraVideoGenerator
        prompt_segments: قائمة بموجهات الأجزاء المختلفة
        model: النموذج المستخدم
    """
    results = []
    config = generator.MODELS[model]
    max_duration = max(config.supported_durations)

    for i, segment_prompt in enumerate(prompt_segments):
        print(f"جاري توليد الجزء {i+1}/{len(prompt_segments)}...")
        result = generator.create_video(
            prompt=segment_prompt,
            seconds=max_duration,
            model=model
        )
        results.append(result)

    return results

# مثال على الاستخدام: توليد فيديو مدته 36 ثانية (3 أجزاء × 12 ثانية)
prompt_segments = [
    "Opening shot: A sunrise over a mountain range, golden light spreading",
    "Middle shot: Birds taking flight from the trees, camera follows",
    "Closing shot: The sun fully risen, peaceful valley below"
]

generator = SoraVideoGenerator(api_key="YOUR_API_KEY")
segments = create_long_video_segments(generator, prompt_segments)
# لاحقاً يمكن استخدام FFmpeg لدمج المقاطع

الأسئلة الشائعة حول أخطاء المدة في Sora 2 API

# ✅ صحيح: استخدام عدد صحيح
seconds=8

# ❌ خطأ: استخدام سلسلة نصية
seconds="8"

VALID_DURATIONS = {
    "sora-2": [4, 8, 12],
    "sora-2-pro": [10, 15, 25]
}

def validate_seconds(model, seconds):
    valid = VALID_DURATIONS.get(model, [])
    if seconds not in valid:
        raise ValueError(f"المدد المدعومة لـ {model} هي: {valid}")
    return True

جدول مرجعي سريع لمعلمة seconds في Sora 2 API

لتسهيل الاستعلام السريع، إليك الجدول المرجعي الكامل لمعلمات المدة الزمنية:

قيم خاطئة شائعة واقتراحات الإصلاح

📌 نصيحة: المنصات المتاحة تشمل APIYI apiyi.com، وOpenAI API الرسمي، وغيرها. نوصي باستخدام المنصات التي توفر أسعاراً تنافسية خلال مرحلة التطوير والاختبار.

ملخص

يُعد خطأ معلمة seconds في Sora 2 API من المشكلات الشائعة التي يواجهها المطورون، وتتمثل فكرة الحل الأساسية في:

1. التمييز بين النماذج: يدعم sora-2 مدد 4/8/12 ثانية، بينما يدعم sora-2-pro مدد 10/15/25 ثانية.
2. مطابقة المعلمات: اختر قيمة المدة الزمنية الصحيحة وفقاً للنموذج المستخدم.
3. التحقق من المعلمات: قم بالتحقق من صحة المعلمات قبل إجراء عملية الاستدعاء (API call).
4. التكيف التلقائي: استخدم فئات الأدوات (utility classes) للتعامل تلقائياً مع مطابقة النموذج والمدة الزمنية.

نوصي باستخدام APIYI apiyi.com لاختبار مجموعات النماذج والمدد الزمنية المختلفة بسرعة للعثور على الإعداد الأمثل.

المؤلف: APIYI Team | لمزيد من تقنيات تطوير الذكاء الاصطناعي، يرجى زيارة apiyi.com

المصادر:

1. وثائق OpenAI Sora API: شرح معلمات توليد الفيديو
   • الرابط: platform.openai.com/docs/api-reference/videos
2. وصف نموذج OpenAI Sora 2: مواصفات النموذج والقيود
   • الرابط: platform.openai.com/docs/models/sora-2
3. دليل أكواد الخطأ في OpenAI: معالجة أخطاء API
   • الرابط: platform.openai.com/docs/guides/error-codes