Seedance 2.5 API: طريقة الاستدعاء والمعلمات والحدود وتكلفة الأرصدة

إجابة مباشرة: يمكنك استدعاء Seedance 2.5 عبر واجهة Yovid API بمفتاح واحد. أرسل POST https://yovid.ai/v1/videos/generations مع "model": "seedance-2.5" وموجّه، ثم استعلم دوريًا عبر GET /v1/tasks/{task_id} حتى تصبح الحالة completed، واقرأ output.video_url. تتراوح مدة المقاطع بين 4 و30 ثانية، ويمكن للطلب الواحد أن يحمل حتى 30 صورة و10 مقاطع فيديو و10 ملفات صوتية كمراجع. ويُحتسب الاستخدام بأرصدة Yovid نفسها المستخدمة في الموقع، ولا تُخصم الأرصدة إلا عند نجاح المهمة.

المحتويات

1. من أين يأتي الوصول إلى Seedance 2.5 API
2. البدء السريع في أربع خطوات
3. معلمات الطلب
4. كيف تختار واجهة API وضع التوليد
5. حدود المراجع والوسائط
6. تكلفة الطلب
7. الأخطاء وإعادة المحاولة وحدود المعدل
8. مثال كامل بلغة Python
9. أسئلة شائعة

من أين يأتي الوصول إلى Seedance 2.5 API

Seedance 2.5 نموذج من ByteDance Seed. ويمر مسار المطورين الخاص بـ ByteDance عبر منصاتها السحابية: فقد ذكر منشور الإطلاق في 31 يوليو 2026 أن الوصول عبر API قادم عبر BytePlus ModelArk، وتقول تقارير صحفية إن Volcano Engine فتحت الوصول عبر API في الصين في 7 أغسطس، وتضع صفحة Seedance 2.5 لدى ByteDance رابطًا إلى بيئة التجربة في BytePlus.

أما Yovid فمنصة مستقلة غير مرتبطة بـ ByteDance، وتقدّم Seedance 2.5 عبر واجهة API الخاصة بها:

• مفتاح واحد وفاتورة واحدة. المفتاح نفسه والأرصدة نفسها تغطي Seedance 2.5 و2.0 و2.0 Fast و2.0 Mini و1.5 Pro و1.0 Pro Fast.
• معرّفات عامة ثابتة. ترسل seedance-2.5؛ ويُبقي Yovid أسماء النماذج لدى المزوّد داخلية حتى يمكن تغييرها دون أن تتعطل شيفرتك.
• الحساب نفسه المستخدم في الموقع. المقاطع التي تولّدها عبر API تستخدم خطتك وأرصدتك الحالية.

المرجع الكامل موجود في وثائق Yovid API؛ ويركّز هذا الدليل على ما يخص Seedance 2.5.

البدء السريع في أربع خطوات

1. أنشئ مفتاح API

افتح الإعدادات ← مفاتيح API، وسمِّ المفتاح ثم أنشئه. يظهر المفتاح السري كاملًا مرة واحدة فقط، لذا خزّنه في مدير أسرار وحمّله على خادمك باسم YOVID_API_KEY. ولا تضعه أبدًا في شيفرة المتصفح أو تطبيق الهاتف.

2. أنشئ مهمة

curl https://yovid.ai/v1/videos/generations \
  -H "Authorization: Bearer $YOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A lighthouse keeper climbs a spiral staircase with a lantern, reaches the lamp room as a storm rolls in, and lights the great lamp. Wind howling, boots on iron steps.",
    "duration": 10,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

{
  "task_id": "vid_01JZK7R7KCYQ3T9F33A7K0J6XB",
  "status": "pending",
  "created_at": "2026-10-22T08:30:00.000Z"
}

3. استعلم عن حالة المهمة

curl https://yovid.ai/v1/tasks/vid_01JZK7R7KCYQ3T9F33A7K0J6XB \
  -H "Authorization: Bearer $YOVID_API_KEY"

استعلم كل 5 إلى 10 ثوانٍ ما دامت الحالة pending أو processing، وباعِد بين الاستعلامات تدريجيًا. وعندما تتحول إلى completed يكون رابط الفيديو في output.video_url؛ وإذا تحولت إلى failed فأوقف الاستعلام واقرأ error.

4. تحقّق من أرصدتك

curl https://yovid.ai/v1/credits \
  -H "Authorization: Bearer $YOVID_API_KEY"

الحقل available هو ما يمكن أن تستخدمه مهمة جديدة؛ أما reserved فهو المحجوز لمهام ما زالت قيد التشغيل.

معلمات الطلب

تتحقق واجهة API من كل قيمة مقارنةً بالنموذج وبخطتك قبل إنشاء المهمة، وتُرجع 403 أو 422 مع اسم الحقل المخالف في param إذا كان هناك ما هو غير مسموح. وإذا بدأت من إطار، فإن المخرجات تتبع شكل تلك الصورة.

كيف تختار واجهة API وضع التوليد

لا ترسل أبدًا وضعًا خاصًا بالمزوّد. يختاره Yovid بناءً على الوسائط التي ترفقها:

في وضع المراجع، أشِر إلى الملفات في الموجّه بحسب ترتيبها في كل مصفوفة: ‎@image1 و‎@image2 و‎@video1 و‎@audio1. ويبدو طلب المراجع هكذا:

{
  "model": "seedance-2.5",
  "prompt": "@image1 is the main character. @image2 is the ceramic mug she holds; keep its shape and logo. @image3 is the kitchen. She walks into the kitchen, pours coffee into the mug and turns to the window. Use @audio1 as her voice: she says, \"Finally, Saturday.\"",
  "image_urls": [
    "https://example.com/character.jpg",
    "https://example.com/mug.jpg",
    "https://example.com/kitchen.jpg"
  ],
  "audio_urls": ["https://example.com/voice-sample.mp3"],
  "duration": 12,
  "quality": "720p"
}

المراجع الصوتية ميزة خاصة بـ API: فأداة الإنشاء في الموقع تقبل الصور ومقاطع الفيديو، بينما تضيف API حتى 10 ملفات صوتية لصوت أو مقطوعة موسيقية أو إيقاع.

حدود المراجع والوسائط

من صفحة النماذج والمدخلات في وثائق API:

يجب أن تكون كل الوسائط روابط عامة عبر HTTPS. ويرفض Yovid عناوين localhost، وعناوين الشبكات الخاصة، والروابط التي تتضمن بيانات اعتماد مضمّنة، وأسماء المضيفين التي يتعذر عليه تحليلها. استخدم الروابط بدل Base64؛ فالمزوّد يحدّ حجم كل طلب بـ 64 ميغابايت.

تكلفة الطلب

تحتسب واجهة API التكلفة بالأرصدة نفسها المستخدمة في الموقع وبالأسعار نفسها. وبالأسعار الأساسية لحزم الأرصدة، يكلّف Seedance 2.5 حوالي 3 أرصدة في الثانية بدقة 480p وحوالي 6.1 بدقة 720p، لذا يكلّف مقطع مدته 10 ثوانٍ بدقة 720p حوالي 61 رصيدًا، ومقطع مدته 30 ثانية حوالي 183. ويدفع المشتركون أقل لكل ثانية.

• الفيديوهات المرجعية تُحتسب على مدة المقطع المرجعي إضافة إلى مدة المخرجات، بسعر أقل: حوالي 2.1 رصيد في الثانية بدقة 480p و4.6 بدقة 720p.
• إيقاف content_filter يضرب التكلفة في 1.1.
• الحجز ثم الخصم. تُحجز الأرصدة عند إنشاء المهمة ولا تُخصم إلا إذا اكتملت؛ والمهمة الفاشلة تُعيدها.
• الوصول بحسب الخطة. يتطلب Seedance 2.5 خطة مدفوعة أو حزمة أرصدة لمرة واحدة. ويحصل الحساب المجاني على ‎403 plan_upgrade_required.

وتُبلغ المهمة المكتملة عمّا استهلكته في credits_used. راجع صفحة الأسعار للاطلاع على الخطط والحزم، ومقال هل Seedance 2.5 مجاني لمعرفة أرخص طريقة للبدء.

الأخطاء وإعادة المحاولة وحدود المعدل

يسمح كل مفتاح بما يصل إلى 120 طلبًا في الدقيقة، وطلبات الاستعلام تُحتسب ضمنها. ولا تدعم نقطة الإنشاء مفاتيح منع التكرار (idempotency keys) بعد، لذا لا تُعِد إرسال طلب POST تلقائيًا إذا كنت لا تعرف هل نجح الطلب الأول: فقد يُنشئ ذلك مهمة ثانية ويحجز الأرصدة مرتين. وسجّل كل task_id تتلقاه.

مثال كامل بلغة Python

import os
import time

import requests

API = "https://yovid.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['YOVID_API_KEY']}"}

create = requests.post(
    f"{API}/v1/videos/generations",
    headers=HEADERS,
    json={
        "model": "seedance-2.5",
        "prompt": (
            "0-10s: a courier in a yellow rain jacket runs out of a subway exit into a night street. "
            "10-20s: she weaves between umbrellas as a taxi brakes. "
            "20-30s: she stops at a door and knocks twice. Rain and traffic, no music."
        ),
        "duration": 30,
        "quality": "720p",
        "aspect_ratio": "16:9",
    },
    timeout=30,
)
create.raise_for_status()
task_id = create.json()["task_id"]

delay = 5
while True:
    task = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
    task.raise_for_status()
    data = task.json()
    if data["status"] == "completed":
        print(data["output"]["video_url"], data["credits_used"])
        break
    if data["status"] == "failed":
        raise RuntimeError(data["error"])
    time.sleep(delay)
    delay = min(delay * 1.5, 30)

يستخدم الموجّه مراحل زمنية، وهي الطريقة الأكثر موثوقية لملء مقطع مدته 30 ثانية. ويضم دليل موجّهات Seedance 2.5 ثلاثة عشر موجّهًا يمكنك إرسالها كما هي، وتساعدك المقارنات مع Kling 3.0 وVeo 3.1 وSeedance 2.0 على اختيار معرّف النموذج الذي تستدعيه.

أسئلة شائعة

هل توجد واجهة API رسمية لـ Seedance 2.5؟

تقدّم ByteDance نموذج Seedance 2.5 للمطورين عبر منصتيها السحابيتين Volcano Engine وBytePlus. أما واجهة Yovid API فبديل مستقل: مفتاح واحد وحساب أرصدة واحد لـ Seedance 2.5 وبقية نماذج Seedance.

ما معرّف نموذج Seedance 2.5 على Yovid؟

المعرّف هو seedance-2.5. والمعرّفات العامة الأخرى هي seedance-2.0 وseedance-2.0-fast وseedance-2.0-mini وseedance-1.5-pro وseedance-1.0-pro-fast.

ما أقصى مدة لفيديو Seedance 2.5 عبر API؟

من 4 إلى 30 ثانية لكل مهمة، وتُضبط عبر duration.

ما درجات الدقة التي تدعمها Seedance 2.5 API؟

تذكر وثائق API دقتَي 480p و720p لـ seedance-2.5. وتحدد خطتك أيضًا سقفًا للدقة، وتُرجع API الرمز 403 قبل إنشاء المهمة إذا كانت الجودة المطلوبة أعلى منه.

هل يمكنني إرسال ملف صوتي كمرجع؟

نعم، حتى 10 ملفات MP3 أو WAV في audio_urls، يُشار إليها في الموجّه بـ ‎@audio1 و‎@audio2 وهكذا. والمراجع الصوتية متاحة عبر API فقط.

هل تكلّف المهمة الفاشلة أرصدة؟

لا. تُحجز الأرصدة عند إنشاء المهمة ولا تُخصم إلا عند اكتمالها بنجاح.

كم طلبًا يمكنني إرساله؟

حتى 120 طلبًا في الدقيقة لكل مفتاح، بما فيها طلبات الاستعلام، إضافة إلى حد للمهام المتزامنة يعتمد على خطتك. والاستجابة 429 تعني أن تنتظر وتعيد المحاولة مع التراجع التدريجي.

هل أنت مستعد للبناء؟ أنشئ مفتاحًا من الإعدادات ← مفاتيح API واتبع دليل البدء السريع لـ API.