الـ webhooks ودورة حياة مهام الوسائط

سجّل mediaWebhookUrl، واستقبل طلب POST عند اكتمال المهمة، واستعلم عبر GET /api/media/jobs/{id}، وتعامل مع رموز الأخطاء، وافهم حدود الفوترة وعدم التكرار.

دليل تشغيلي لمهام الوسائط غير المتزامنة: تسجيل webhook، والحالات، والاستطلاع، وأكواد الأخطاء، والرسوم، وحدود idempotency — بدقة وفقًا للتنفيذ الحالي في الكود.

دورة حياة المهمة

POST /api/media/generate — عند النجاح 202 و{ ok: true, jobId, status: "processing" }. ولا توجد في الـ API حالتان منفصلتان queued / running: فحتى انتهاء المهمة يرى العميل processing.
قد يمرّ المزوّد upstream بمراحل داخلية (waiting، generating) — وهي لا تظهر في واجهة API العامة؛ وأثناء الاستعلام يبقى المهمة processing.
الحالات النهائية: success (يحمل resultUrls، ويُحتسب عند النجاح) أو fail (دون احتساب).
يُسجَّل الإكمال مرة واحدة: عبر رد الاتصال من المصدر أو عند استعلام مؤجَّل في GET /api/media/jobs/{id}.

الاستعلام: GET /api/media/jobs/{id}

GEThttps://getvibeapi.com/api/media/jobs/{id}

المعلمة	النوع	الوصف
`status`	string	submitting \| processing \| success \| fail. submitting + media_submission_uncertain is non-terminal; within about 10–15 minutes such a submission is closed as fail (media_submission_not_started) without a charge — create a new task.
`resultUrls`	string[]	روابط موقّعة /api/media/file/{id}/{idx}?sig=… (بدون مفتاح API).
`priceRub`	number	مبلغ الرسوم بالدولار الأمريكي (0 عند الفشل أو قبل الاكتمال).
`failMsg`	string \| null	رسالة آمنة عند الفشل أو عند وجود media_submission_uncertain غير نهائي.
`errorCode`	string \| null	رمز الخطأ (media_generation_failed) أو media_submission_uncertain غير النهائي.
`retryGuidance`	string \| null	عند ظهور media_submission_uncertain: إرشاد آمن لإعادة الاستعلام عن المهمة نفسها jobId لاحقًا وعدم إنشاء مهمة مكررة تلقائيًا.

# 2. poll the job until it is ready
curl https://getvibeapi.com/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $GETVIBE_API_KEY"
# → {"status":"success","resultUrls":["https://..."],"priceRub":...}

الفاصل الموصى به للاستقصاء الدوري: 3–5 ثوانٍ، مع تراجع أُسّي يصل إلى 30 ثانية. وتُحدد مهلة العميل وفق اتفاقية مستوى الخدمة لتطبيقك (قد يستغرق توليد الفيديو دقائق).

تسجيل الـ webhook

GEThttps://getvibeapi.com/api/webhooks

PATCHhttps://getvibeapi.com/api/webhooks

عنوان URL واحد لكل حساب: mediaWebhookUrl. يُضبط في dashboard → Webhooks أو عبر API باستخدام جلسة الحساب (ملف ارتباط بعد تسجيل الدخول). ونقطة النهاية لا تقبل sk-pv-… — بل جلسة موثّقة فقط.

# Example (a dashboard session is required, not an API key)
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":"https://example.com/webhooks/media"}'

# Clear the URL
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":null}'

متطلبات URL

المعلمة	النوع	الوصف
`mediaWebhookUrl`	HTTPS URL	عنوان HTTPS عام؛ تُرفض العناوين الخاصة/عناوين الاسترجاع الذاتي ونطاقاتنا الخاصة (للحماية من SSRF)، ويُعاد التحقق من العنوان قبل كل عملية تسليم. تعيد السلسلة الفارغة أو null ضبطه.
`balanceWebhookUrl`	HTTPS URL	Webhook منفصل لانخفاض الرصيد (وليس للوسائط)، ويُوقّع باستخدام سر الحساب نفسه، x-pv-event: balance.low. الحد الأدنى هو balanceWebhookThresholdRub.

تسليم الـ webhook عند اكتمال المهمة

عندما تصل المهمة إلى حالة نهائية، يُنشئ GetVibe حدثًا منطقيًا واحدًا ويسلّمه عبر POST إلى mediaWebhookUrl المسجَّل. التسليم محدود: تقدّم الخدمة حتى 5 محاولات إجمالًا. وقد تصل الحمولة نفسها أكثر من مرة.

// POST to your mediaWebhookUrl when a job finishes
{
  "jobId": "...",
  "status": "success",            // or "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://getvibeapi.com/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

سلوك التسليم (كما في الشيفرة)

المعلمة	النوع	الوصف
`Signature / auth`	—	يُوقَّع كل تسليم باستخدام Standard Webhooks: الرؤوس webhook-id وwebhook-timestamp وwebhook-signature (v1، وHMAC-SHA256 بترميز base64 للقيمة “id.timestamp.body”). يظهر سر الحساب في لوحة التحكم → Webhooks، ويُعاد إلى مفتاح API باسم accountSecret عبر GET /api/media/webhook-secret؛ وتُوقَّع عمليات التسليم إلى webhook_url المحدد لكل طلب باستخدام سر ذلك المفتاح (الحقل secret). ارفض أي طلب ذي توقيع غير صحيح أو طابع زمني أقدم من 5 دقائق.
`Retries`	outbox	حتى 5 محاولات إجمالًا؛ والفاصل بعد كل فشل: 1، 2، 4، 8 دقائق. وبعد استنفاد المحاولات ينتقل الحدث إلى FAILED ولم يعد يُسلَّم تلقائيًا. ويبقى الاستعلام GET /api/media/jobs/{id} هو مصدر الحالة.
`Receiver dedup`	required	أزل التكرار وفق زوج jobId + status واجعل المعالج خاملًا تكرارًا (idempotent). لا تستخدم الـ webhook كمصدر الحالة الوحيد.
`Content-Type`	application/json	الجسم JSON بحقول jobId وstatus وmodel وkind وresultUrls وfailMsg وcreatedAt.

أخطاء POST /api/media/generate

HTTP	متى	الرسوم	إعادة المحاولة
202	تم قبول المهمة (ok: true, jobId)	لا (فقط بعد النجاح)	—
400	JSON غير صالح / جسم الطلب	لا	أصلح الطلب
401	مفتاح API مفقود أو غير صالح	لا	التحقق من Authorization
402	رصيد غير كافٍ (القبول)	لا	اشحن الرصيد
422	طراز غير معروف، خيارات غير صالحة، ok: false من الواجهة	لا	Fix model/opts
502	media_submit_failed — المورّد غير متاح	لا	إعادة المحاولة مع التراجع التدريجي
503	priceUnavailable، وحارس التوجيه، وVIDEO_DISABLED، وveo دون سعر	لا	طراز آخر / لاحقًا

أخطاء الاستعلام والفشل النهائي

HTTP / الحالة	المعنى	الرسوم
404	المهمة غير موجودة أو jobId تابع لجهة أخرى	لا
processing	المهمة ما زالت قيد التنفيذ	لا
success	تم، وامتلأت resultUrls	نعم — priceRub في الإجابة
fail	فشل التوليد	No (priceRub = 0)

الفوترة وعدم التكرارية

يُحتسب مرة واحدة عند النجاح. في finalizeJob يكون الانتقال processing → success|fail ذرّيًا: فتكرار الاستدعاء أو الاستعلام لا ينشئ احتسابًا ثانيًا.
fail — مجانًا. لا يُخصم أي مبلغ عند الحالة fail.
عرض السعر عند القبول. إذا حُفظ عرض سعر عند الإنشاء، فسيُحتسب هو نفسه بالضبط عند النجاح (ولن يتجاوز أبدًا القياس الفعلي لدى المزوّد الأعلى).
إنشاء مفتاح منع التكرار — عبر الترويسة. إرسال POST متكرر إلى /api/media/generate دون الترويسة ينشئ مهمة جديدة واحتسابًا جديدًا عند النجاح. أرسل Idempotency-Key (حتى 255 حرفًا ASCII): إعادة المحاولة بالمفتاح والجسم نفسيهما خلال 24 ساعة تعيد jobId نفسها دون مهمة جديدة؛ أما المفتاح نفسه مع جسم مختلف فيعيد 422، و409 ما دام الطلب الأول قيد المعالجة. ويظهر jobId الخاص بالتوليد المدفوع أيضًا في GET /v1/generations (الحقل job_id).
الـ Webhook محدود بخمس محاولات. يُنشأ حدث منطقي واحد لكل انتقال نهائي، لكن محاولات التسليم قد تتكرر. وبعد خمس محاولات فاشلة يكتسب الحدث الحالة FAILED. ويجب على معالج العميل إزالة تكرار الزوج jobId + status.

انظر أيضاً: توليد الوسائط، كتالوج طرازات الوسائط، الأخطاء والحدود (رموز 401/402/429 الشائعة لـ /v1).

← السابقكتالوج نماذج الوسائط التالي →الرصيد والاستخدام