> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> تتبّع المهام غير المتزامنة واستقبل الويب هوك ومرّر خيارات الفيديو الخاصة بالمزوّد.

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

تعيد عمليات إنشاء الفيديو ومعالجة الدفعات مهمة قبل اكتمال العمل. احفظ `id` الخاص بها واستخدم `polling_url` المعاد لاستعادة أحدث حالة. لا تعني استجابة الإنشاء الناجحة اكتمال الإنشاء أو معالجة الدفعة.

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

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

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

```json theme={null}
{
  "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` لتحديد الإطار الأول والأخير صراحةً:

```json theme={null}
{
  "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` بالثواني.

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

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

```json theme={null}
{
  "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 النموذج](https://www.atlascloud.ai/models/bytedance/seedance-2.5/reference-to-video) |
| Novita Seedance 1.5 | `watermark`, `camera_fixed`, `fps` (24), `service_tier` (`default`) | [API الفيديو الموحّدة](https://docs.novita.ai/api-reference/reference-unified-video-generation) |
| BytePlus Seedance | `camera_fixed` | تحقق من عقد المزوّد للنموذج المحدد قبل الاستخدام. |
| MiniMax V1 | `fast_pretreatment`؛ استخدم `enhance_prompt` القياسي لتحسين المطالبات | [API الفيديو](https://platform.minimax.io/docs/api-reference/video-generation-t2v) |

يستخدم 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](https://platform.minimax.io/docs/api-reference/video-generation-v2-create).

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

تقبل طلبات الدفعات `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 المعتاد من مساحة العمل المالكة للدفعة:

```bash theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.