البناء باستخدام واجهة برمجة تطبيقات Seevio

اختر نموذجًا

يتضمن مرجع كل نموذج معلماته الكاملة، وأسعاره، وأمثلة عليه. يمكنك إتمام عملية الدمج بالكامل من صفحة نموذج واحد.

المصادقة

أنشئ مفتاح API في لوحة التحكم. يظهر المفتاح الكامل مرة واحدة فقط. احتفظ به في خادمك وأرسله كرمز حامل (Bearer token) مع كل طلب.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

قم بتعيين متغير البيئة SEEVIO_API_KEY قبل تشغيل هذه الأمثلة. يتم تشغيل أمثلة JavaScript على خادمك باستخدام Node.js؛ وتستخدم أمثلة Python حزمة requests.

البدء السريع

يولد هذا المثال فيديو مدته 5 ثوانٍ بدقة 720p باستخدام Seedance 2.5. افتح مرجع النموذج للاطلاع على كافة أوضاع التوليد وحدود المعلمات.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

مثال على استجابة إنشاء المهمة

بعد قبول الطلب أعلاه، ترجع واجهة برمجة التطبيقات (API) استجابة JSON هذه. يمثل taskId معرف المهمة المستخدم في عمليات الاستعلام اللاحقة عن الحالة؛ بينما يمثل credits عدد النقاط المحجوزة لهذه المهمة. تؤكد هذه الاستجابة إنشاء المهمة بنجاح، ولا تعني أن الفيديو جاهز بعد. يتعين عليك تتبع حالة المهمة بشكل دوري (Poll) أو استخدام Webhook لتلقي نتائج الفيديو.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

الاستعلام عن مهمة

استبدل معرف المثال بـ taskId المسترجع من عملية الإنشاء. تعيد الاستعلامات فقط المهام المملوكة لمستخدم مفتاح API؛ وتعيد المعرفات غير المعروفة أو التي لا يمكن الوصول إليها خطأ HTTP 404.

استعلم كل 10–20 ثوانٍ كخطوة أولى، وتراجع مؤقتًا عند تلقي HTTP 429، وتوقف عندما تصبح الحالة completed أو failed. يُفضل استخدام خطاطيف الويب (webhooks) في بيئة الإنتاج. يقوم كل مثال كود أدناه باستعلام واحد.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

مهمة مكتملة: استجابة الاستعلام مع نتائج الفيديو

عندما ترجع نتيجة الاستعلام status=completed، فهذا يعني أن عملية إنشاء الفيديو قد انتهت بنجاح. يمكنك قراءة روابط الفيديو من data.results وتنزيلها قبل حلول تاريخ data.video_expires_at. تشير القيمة billing_status=charged إلى أنه تم خصم الرصيد المحجوز بالفعل.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

مهمة فاشلة: استجابة الاستعلام مع تفاصيل الفشل والفوترة

عندما ترجع نتيجة الاستعلام status=failed، فهذا يعني أن عملية الإنشاء قد انتهت دون نجاح. يمكنك قراءة سبب الفشل من failed_reason وحالة الفوترة من billing_status لمعرفة تفاصيل عملية الاسترداد. في هذا المثال، تعني refunded أنه تمت إعادة الرصيد المحجوز. يحتفظ الحقل credits بالقيمة الأصلية المحجوزة، ولا تتضمن الاستجابة أي بيانات في data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

خطاطيف الويب (Webhooks)

لعلميات الدمج في بيئة الإنتاج، يرجى تزويد callback_url عند إنشاء المهمة. يتضمن مرجع كل نموذج بيانات الاستجابة الراجعة ومثالاً على خادم الاستقبال.

اضبط callback_url في طلب الإنشاء لتلقي طلب JSON POST عند اكتمال المهمة أو فشلها. يجب إرجاع استجابة بترميز 2xx في غضون 15 ثانية. تتم إعادة المحاولة للإرسال الفاشل؛ لذا يرجى معالجة الطلبات المتكررة بشكل متطابق (idempotently) باستخدام معرف المهمة.

يجب أن تدعم نقطة نهاية الاستدعاء الذاتي (Callback endpoint) استقبال طلبات من نوع POST مع نص طلب بتنسيق JSON ‏(Content-Type: application/json).

إنشاء مهمة مع تعيين خطاف الويب (callback)

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

تختلف بيانات خطاطيف الويب عن استجابات استعلام المهام: فهي تحذف billing_status و credits؛ وتكون تفاصيل الفشل داخل data.failed_reason و data.credits_refunded. حقل created_at في خطاف الويب يمثل وقت إنشاء الحدث بثواني Unix.

اكتملت المهمة: بيانات الاستدعاء الذاتي الناجح

عند نجاح عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=completed. استخدم المعرّف (id) لتحديد المهمة، وdata.results للحصول على روابط الفيديو. يُرجى تنزيل النتائج وحفظها قبل تاريخ صلاحية الفيديو الموضح في data.video_expires_at.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

فشلت المهمة: بيانات استدعاء ذاتي غير ناجح

عند فشل عملية الإنشاء، ستحتوي استجابة الاستدعاء الذاتي على status=failed. استخدم المعرّف (id) لتحديد المهمة، وdata.failed_reason لمعرفة سبب الفشل، وdata.credits_refunded لمعرفة عدد الرصيد المسترد.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

مثال للمستقبل (Receiver)

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

يقرأ نموذج Next.js هذا نص استجابة JSON للتعامل مع المهام المكتملة والفاشلة مباشرةً. يُرجى إضافة ميزة الحفظ الدائم وتجنب تكرار معرفات المهام (Task-ID) في تطبيقك، مع جدولة المهام البطيئة في قائمة انتظار قبل تأكيد الاستدعاء الذاتي.

الأخطاء

تحتوي أخطاء HTTP على كائن خطأ يضم الرمز (code) والرسالة (message). يمكن للمهمة المقبولة بنجاح أن تفشل لاحقًا؛ لذا استعلم عن المهمة أو تعامل مع خطاك الراجع للفشل.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}