مهام الفيديو والدفعات

واجهتا Video API وBatch API معاينتان تجريبيتان متاحتان بالدعوة فقط لمساحات عمل محددة. تحقق من التوفر في الإعدادات → معاينة الميزات. يُدار الوصول لكل مساحة عمل؛ تفعيل تفضيل ويب شخصي لا يمنح الوصول إلى API. تطبق رسوم استخدام النماذج المعتادة.

تعيد عمليات إنشاء الفيديو ومعالجة الدفعات مهمة قبل اكتمال العمل. احفظ id الخاص بها واستخدم polling_url المعاد لاستعادة أحدث حالة. لا تعني استجابة الإنشاء الناجحة اكتمال الإنشاء أو معالجة الدفعة. خلال الإصدار التجريبي، ابدأ بطلبات صغيرة وحد إنفاق لمفتاح API. تختلف إمكانات المزوّدين والنماذج؛ وتعتمد المدخلات المرجعية والإلغاء والاحتفاظ بالمخرجات على المزوّد المحدد. احتفظ بنسختك من المخرجات المكتملة قبل انتهاء صلاحيتها.

تلقي التحديثات

أرفق نقطة نهاية ويب هوك تابعة لمساحة عملك عند إنشاء أي من نوعي المهام:

{
  "webhook": {
    "endpoint_id": "YOUR_ENDPOINT_ID",
    "events": ["job.status_changed", "job.completed", "job.failed", "job.cancelled", "job.expired"]
  }
}

يطابق Phaseo حالة المزوّد ويرسل إشعارات للعميل. يمكن للمزوّدين الذين يتطلبون الاستقصاء الدوري، بما في ذلك دفعات رسائل Anthropic، إرسال ويب هوك للعملاء أيضًا. فشل تسليم الويب هوك منفصل عن فشل الإنشاء أو الدفعة. يمكن لاشتراكات نقاط النهاية استهداف أحداث الدفعات والفيديو بصورة مستقلة. استخدم أنواع الأحداث ذات نطاق الأسماء مثل batch.completed أو video.failed؛ تظل أنواع job.* العامة مدعومة وتشترك في المرحلة المقابلة لكلا نوعي المهام. تحقق من x-phaseo-signature باستخدام سر نقطة النهاية: التوقيع هو HMAC-SHA256 بالصيغة السداسية العشرية لـx-phaseo-timestamp ونقطة حرفية ونص الطلب غير المعدّل بعد وصلها. تحقق من حداثة الطابع الزمني وأزل التكرار باستخدام x-phaseo-event-id وأكّد التسليمات المقبولة باستجابة HTTP ناجحة. قد يعاد التسليم أو تصل الأحداث بترتيب مختلف؛ استرجع المهمة قبل تطبيق تغيير حالة متعارض. بعد حفظ نقطة النهاية، استخدم إرسال حدث اختباري في الإعدادات لتسليم حمولة webhook.test موقّعة. تُجرَّب التسليمات الاختبارية مرة واحدة ولا يعاد إرسالها أو إضافتها إلى سجل تسليمات المهمة. اعتبر حالات دورة الحياة completed وfailed وcancelled وexpired نهائية. احتفظ بمسار استعادة عبر الاستقصاء الدوري حتى عند استخدام الويب هوك. يجري Phaseo محاولة تسليم أولية لكل حدث. تنهي استجابة 2xx الناجحة التسليم دون الحاجة إلى إعادة المحاولة. تتلقى التسليمات الفاشلة حتى ثلاث محاولات إضافية مجدولة بعد 1 و5 و15 دقيقة. تعالج عمليات المسح الخلفية المحاولات المستحقة، لذا قد يتأخر التسليم الفعلي عن الوقت المجدول. تسجّل كل محاولة رقمها ووقتها وحالة HTTP والخطأ ووقت المحاولة التالية. بعد المحاولة الرابعة غير الناجحة يُعلّم التسليم بأنه فشل نهائيًا. يجب على المستقبلين مواصلة إزالة الأحداث المكررة: فقدان التأكيد أو انقطاع worker قد يجعل نتيجة التسليم غير مؤكدة.

عرض سجلات المهام والطلبات

في الإعدادات → الاستخدام → السجلات، استخدم الطلبات لتفاصيل طلبات الاستدلال والفيديو لدورات حياة الفيديو والدفعات لمهام الدفعات ونتائج الصفوف. تشمل تفاصيل الفيديو والدفعات حالة الفوترة ومحاولات المزوّد ومحاولات الويب هوك. قد تكتمل المهمة بنجاح بينما يفشل تسليم الويب هوك الخاص بها. يحجز إرسال الفيديو الرصيد قبل الاتصال بالمزوّد. عند انتهاء المهلة دون معرّف مهمة، يبقى الحجز للمطابقة؛ وهذا ليس دليلًا على فشل الإنشاء. إذا سُعّر حجز فيديو أو دفعة مدفوع بشكل غير متوقع بصفر بعد نجاح العمل، تبقى الفوترة مفتوحة مع unexpected_zero_cost للتحقيق. استجابة إنشاء بتكلفة صفر وحدها أمر طبيعي في الإنشاء غير المتزامن.

مدخلات الفيديو

فهم أسعار الفيديو

تعتمد أسعار الفيديو على المزوّد والنموذج. يجب ضرب السعر لكل ثانية في المدة القابلة للفوترة؛ أما السعر لكل مقطع فينطبق فقط على مدته ودقته المحددتين. قد تزيد المخرجات المتعددة والمدخلات المرجعية المدفوعة الإجمالي. يفوتر إنشاء النص/الصورة في LTX ثواني المخرجات، بينما يفوتر تحويل الصوت إلى فيديو ثواني الصوت المدخل. يستخدم BytePlus Seedance توكنات فيديو بأسعار مختلفة عند وجود فيديو مرجعي. يستخدم MiniMax Hailuo V1 أسعار مقاطع بمدة ثابتة؛ ويستخدم H3 الثواني وقد يفرض رسومًا على المدخلات المرجعية. تحقق من أبعاد تسعير المزوّد المحدد بدل اعتبار السعر البارز تكلفة الطلب بأكمله. الحجوزات تقديرات تُحتجز قبل الإرسال. تستخدم الفوترة النهائية الاستخدام القابل للفوترة للمهمة؛ ويُحرّر الرصيد المحجوز غير المستخدم بعد المطابقة. دعم المزوّد لدقة أو خيار لا يضمن توفره في الإصدار التجريبي. استخدم seconds أو duration لمدة المخرجات. إذا وُجدا معًا، يجب أن يتطابقا. استخدم resolution مع aspect_ratio أو size بالبكسل مثل 1280x720. استخدم frame_images لتحديد الإطار الأول والأخير صراحةً:

{
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": { "url": "https://example.com/start.png" }
    }
  ],
  "input_references": [
    {
      "type": "image_url",
      "role": "reference",
      "image_url": { "url": "https://example.com/character.png" }
    }
  ]
}

يجب أن تستخدم عناوين URL المرجعية HTTPS. حدد role: "reference" صراحةً للصور المرجعية فقط: الطلبات القديمة دون frame_images تفسّر أول صورة بلا تسمية على أنها الإطار الأول. لا تجمع frame_images مع أدوار الإطار الأول/الأخير في input_references أو مع input_reference. تستخدم مراجع الفيديو والصوت type: "video_url" أو "audio_url" وmedia_url: { "url": "https://..." }. تدعم النماذج والمزوّدون تركيبات مختلفة. عندما تؤثر مدة المرجع في السعر، قدّم input_video_duration وinput_audio_duration بالثواني.

خيارات المزوّد

أبقِ النموذج والمدة والدقة وإنشاء الصوت ووسائط الإدخال وعدد المخرجات في الحقول القياسية. مرّر امتدادات المزوّد الخاصة تحت معرّفه القياسي:

{
  "provider_options": {
    "atlascloud": { "watermark": false, "output_format": "mp4" },
    "byteplus": { "camera_fixed": true }
  }
}

تُمرّر خيارات المزوّد المحدد فقط. لا تختار الخيارات مزوّدًا؛ استخدم إعداد التوجيه provider لذلك. لا تجمع provider_options مع provider_params القديم. لا يمكن للخيارات المتداخلة تجاوز حقول الفوترة أو الاستدعاء الراجع التي تتحكم فيها البوابة.

المزوّد	أمثلة على الامتدادات الأصلية	المرجع
AtlasCloud Seedance 2.5	`watermark`, `output_format`, `return_last_frame`, `omni_reference_task_type`	API النموذج
Novita Seedance 1.5	`watermark`, `camera_fixed`, `fps` (24), `service_tier` (`default`)	API الفيديو الموحّدة
BytePlus Seedance	`camera_fixed`	تحقق من عقد المزوّد للنموذج المحدد قبل الاستخدام.
MiniMax V1	`fast_pretreatment`؛ استخدم `enhance_prompt` القياسي لتحسين المطالبات	API الفيديو

يستخدم AtlasCloud Seedance الحقول الأصلية resolution وratio وlast_image. تتلقى نسخته لتحويل المراجع إلى فيديو مراجع مرتبة للصور والفيديو والصوت. لا يدعم عقد الحجز ثابت المدة في البوابة التحرير بمدة تلقائية (duration: -1). يجب ضبط توفر نماذج المزوّد وأسعارها قبل توجيه نموذج؛ خيار المزوّد لا يفعّل نموذجًا غير متاح. يستخدم MiniMax H3 الإصدار V2: من 4 إلى 15 ثانية كاملة بدقة 768P أو 2K. يدعم H3 Max من 5 إلى 15 ثانية كاملة بدقة 480P أو 768P مع نص أو صور إطارات. يدعم H3 مراجع الصور والفيديو والصوت؛ ولا يمكن خلط المراجع مع الإطارات الأولى/الأخيرة. ينتج كلا النموذجين فيديو واحدًا لكل طلب ولا يدعمان خيارات تحسين المطالبات في V1. استخدم aspect_ratio القياسي؛ تحدد مدخلات الإطارات نسبتها الخاصة. تغطي حجوزات الفيديو المرجعي حد إدخال المزوّد البالغ 15 ثانية، وتُسوّى الكمية الفعلية عند الاكتمال. راجع عقد MiniMax V2.

مزوّدو الدفعات

تقبل طلبات الدفعات provider_options أيضًا: يدعم OpenAI الحقل output_expires_after ويدعم Mistral الحقل metadata. استخدم معرّفات المزوّدين القياسية ولا تكرر هذه الحقول في المستوى الأعلى. مثلًا، يضبط provider_options: { "openai": { "output_expires_after": { "anchor": "created_at", "seconds": 86400 } } } الاحتفاظ بمخرجات OpenAI. لا يمكن تجاوز مدخلات الصفوف أو النماذج أو نقاط النهاية أو وجهات الويب هوك عبر الخيارات. لدى Mistral محوّل دفعات أصلي بالفعل. تُستقصى دفعات رسائل Anthropic دوريًا؛ وقد يجمع مزوّدون آخرون الاستقصاء مع إشعارات الاكتمال الأصلية. يعتمد التوفر على نقاط النهاية التي يدعمها المزوّد وقائمة السماح للدفعات في النشر. تحقق من استجابة إمكانات الدفعات قبل إرسال ملف أو طلبات مضمنة. قد تحتوي الدفعة المكتملة على صفوف فاشلة. افحص كل نتيجة بمعرّفها المخصص بدل افتراض نجاح كل الصفوف. احتفظ بالمدخل الأصلي ومعرّف المهمة حتى مطابقة النتائج والفوترة. يجب التحقيق في الإرسال غير المؤكد قبل تكراره، لأن المزوّد ربما قبل الطلب الأصلي.

تنزيل نتائج الدفعات

بعد بلوغ دفعة مدعومة حالة نهائية، يشير results_url الخاص بها إلى تنزيل Phaseo يتطلب المصادقة. استخدم مفتاح Phaseo API المعتاد من مساحة العمل المالكة للدفعة:

curl --fail "https://api.phaseo.app/v1/batches/$BATCH_ID/results" \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  --output results.jsonl

تبث الاستجابة JSONL عبر نقطة النهاية نفسها لكل مزوّد دفعات مدعوم. يجمع Phaseo ملفات النجاح والأخطاء المنفصلة، ويحوّل مصفوفات النتائج المضمنة إلى JSONL، ويتابع صفحات النتائج. يُحفظ المحتوى المنشأ وأخطاء كل طلب. تظل حقول الصفوف بصيغة المزوّد الأصلية: استخدم custom_id للصفوف المتوافقة مع OpenAI وصفوف Anthropic، وبيانات الطلب الوصفية لـGemini، وbatch_request_id لـxAI. تحتوي صفوف Anthropic الناجحة على الرسالة المنشأة في result.message. تدعم التنزيلات محوّلات OpenAI وAnthropic وGoogle AI Studio وMistral وTogether وGroq وAlibaba Cloud وMoonshot وParasail وOVHcloud وxAI. يظل توفر المزوّد معتمدًا على وصول المعاينة وقائمة السماح بالإرسال؛ دعم التنزيل لا يفعّل مسارات إضافية. تبقى output_file_id وerror_file_id ونقاط نهاية محتوى الملفات الحالية متاحة. تحتوي نقطة نهاية صفوف طلبات الدفعة على بيانات وصفية للتتبع والفوترة، لا على نصوص الرسائل المنشأة. تنزيل النتائج لا يرسل دفعة أخرى ولا يضيف رسوم استدلال. لا تحتاج إلى بيانات اعتماد المزوّد. تشير الويب هوك إلى تحديثات المهمة؛ نزّل النتائج بشكل منفصل. قد تكون للمهمة النهائية نتائج جزئية أو لا مخرجات إطلاقًا: تعيد نقطة النهاية 409 أثناء المعالجة و404 عند غياب المخرجات. احفظ النتائج قبل انتهاء فترة احتفاظ المزوّد. إذا انقطع التنزيل، تجاهل الملف الجزئي وأعد التنزيل، لا إرسال الدفعة. تُبث نتائج JSON المضمنة بحد أمان 8 MiB لكل صف؛ أما ملفات JSONL الأصلية فتُبث دون حد الصف هذا. للمخرجات الكبيرة، تعيد client.batches.streamResults(batchId, { signal }) في TypeScript تدفق ReadableStream<Uint8Array> دون تخزين مؤقت. وجّه التدفق إلى وجهتك وألغِه أو أوقف الإشارة للتوقف مبكرًا؛ لا توجد مهلة إجمالية ثابتة للتنزيل. تنتج client.batches.stream_results(batch_id) في Python كتل بايتات بمهلة HTTP المضبوطة؛ أغلق المكرّر عند التوقف مبكرًا. تعيد عمليات retrieveBatchResults المنشأة نص JSONL كاملًا وتناسب المخرجات الصغيرة أكثر.

حدود تنزيل الدفعات

تسمح تنزيلات نتائج الدفعات بـ10 محاولات لكل مساحة عمل ولكل دفعة خلال نافذة متحركة مدتها 30 دقيقة، مشتركة بين مفاتيح API والاسمين البديلين /batches و/batch. تُحسب المحاولات التي تصل إلى قبول التنزيل حتى إن فشل تنزيل المزوّد أو أُلغي. لا تُحسب إخفاقات الملكية والجاهزية. تتضمن استجابة 429 الحقل Retry-After بالثواني. إذا كان محدد المعدل غير متاح، تعيد التنزيلات 503 مع Retry-After: 30.

نظرة عامة

النماذج والتوجيه

الميزات

التكاملات

مساحات العمل والوصول

الموثوقية والعمليات

المنصة والأبحاث

أدلة الترحيل

المجتمع

مهام الفيديو والدفعات

تلقي التحديثات

عرض سجلات المهام والطلبات

مدخلات الفيديو

فهم أسعار الفيديو

خيارات المزوّد

مزوّدو الدفعات

تنزيل نتائج الدفعات

حدود تنزيل الدفعات

​تلقي التحديثات

​عرض سجلات المهام والطلبات

​مدخلات الفيديو

​فهم أسعار الفيديو

​خيارات المزوّد

​مزوّدو الدفعات

​تنزيل نتائج الدفعات

​حدود تنزيل الدفعات

تلقي التحديثات

عرض سجلات المهام والطلبات

مدخلات الفيديو

فهم أسعار الفيديو

خيارات المزوّد

مزوّدو الدفعات

تنزيل نتائج الدفعات

حدود تنزيل الدفعات