واجهة برمجة تطبيقات عامة

إنشاء فيديوهات وصور وموسيقى من كودك الخاص

أنشئ مفتاحًا، أرسل طلبًا مع مصادقة Bearer وراقب المهمة حتى يصبح ملفك جاهزًا. نفس النماذج والأسعار وحدود الخطط والاستردادات كما في استوديو NovaMotions AI، من رصيد ائتمانات مشترك واحد.

احصل على مفتاح API البدء السريع

عنوان URL الأساسيhttps://novamotions.com/api/v1

البدء السريع

ثلاث خطوات من الصفر إلى فيديو مكتمل. كل طلب هو HTTPS عادي مع JSON، لذا أي لغة أو أداة تعمل.

1
إنشاء مفتاح
افتح صفحة API في حسابك وأنشئ مفتاحًا. يُعرض المفتاح الكامل مرة واحدة فقط، لذا خزنه في متغير بيئي باسم API_KEY.
إنشاء مفتاح

إرسال مهمة

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

curl -X POST https://novamotions.com/api/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-pro",
    "prompt": "لقطة دوللي بطيئة عبر شارع نيون ممطر ليلاً، انعكاسات على أسفلت مبلل، سينمائي",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

راقب حتى يصبح جاهزًا

تحقق من المهمة كل بضع ثوانٍ. عندما تكون الحالة ناجحة، قم بتنزيل الملف من output_url. إذا فشلت، تُعاد الائتمانات إلى رصيدك.

TASK_ID=your_task_id
while true
do
  TASK=$(curl -s https://novamotions.com/api/v1/tasks/$TASK_ID -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo "$TASK" | jq -r .status)
  echo "$STATUS"
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]
  then
    echo "$TASK" | jq
    break
  fi
  sleep 5
done

المصادقة

أرسل مفتاحك في رأس Authorization لكل طلب. تبدأ المفاتيح بـ nm_live_ وتنتمي إلى حساب واحد.

HTTP

Authorization: Bearer nm_live_your_api_key
Content-Type: application/json

عنوان URL الأساسي: جميع نقاط النهاية تحت https://novamotions.com/api/v1 وتُرجع JSON.
حافظ على سرية المفاتيح: اتصل بالـ API من خادمك، لا من المتصفح أو تطبيق الهاتف. المفتاح الملغى يتوقف عن العمل فورًا.
رصيد واحد: تستهلك مكالمات API ائتمانات مالك المفتاح، نفس الرصيد الذي يستخدمه الاستوديو. تنطبق أيضًا حدود الخطة لكل إنشاء.
عناوين الوسائط: يجب أن تكون الصور والفيديوهات والصوتيات التي تمررها عناوين https عامة تُحمّل بدون ملفات تعريف ارتباط أو تسجيل دخول.

قائمة النماذج

GET/api/v1/models

كل نموذج يخدمه API، مع أوضاعه، مدده، دقته، نسب العرض إلى الارتفاع، دعم الصوت، حدود المراجع وأدنى سعر له بالائتمانات. استخدمه لبناء منتقي نموذج بدلاً من ترميز الخيارات يدويًا.

طلب

curl https://novamotions.com/api/v1/models \
  -H "Authorization: Bearer $API_KEY"

استجابة

JSON

{
  "object": "list",
  "data": [
    {
      "slug": "seedance-2-pro",
      "name": "Seedance 2.0 Pro",
      "kind": "video",
      "endpoint": "/api/v1/videos",
      "available": true,
      "modes": [
        "text-to-video",
        "image-to-video",
        "reference-to-video"
      ],
      "durations": [
        4,
        5,
        6,
        8,
        10,
        12,
        15
      ],
      "default_duration": 5,
      "resolutions": [
        "480p",
        "720p",
        "1080p",
        "4K"
      ],
      "aspect_ratios": [
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4",
        "21:9"
      ],
      "audio": {
        "supported": true,
        "extra_credits": 20
      },
      "references": {
        "images": 9,
        "videos": 3,
        "audio": 3,
        "end_frame": true
      },
      "max_count": 4,
      "prompt_max_length": 10000,
      "from_credits": 35
    }
  ]
}

التحقق من الرصيد

GET/api/v1/balance

الائتمانات التي يمكن لمالك المفتاح إنفاقها الآن، مقسمة إلى مجموعات مع تواريخ انتهاء صلاحيتها، بالإضافة إلى الخطة الحالية.

طلب

curl https://novamotions.com/api/v1/balance \
  -H "Authorization: Bearer $API_KEY"

استجابة

JSON

{
  "object": "balance",
  "balance": 1175,
  "never_expiring": 375,
  "next_expiry": "2026-11-17T00:00:00.000Z",
  "pools": [
    {
      "source": "subscription",
      "remaining": 800,
      "granted": 2000,
      "expires_at": "2026-11-17T00:00:00.000Z"
    },
    {
      "source": "topup",
      "remaining": 375,
      "granted": 375,
      "expires_at": null
    }
  ],
  "plan": {
    "name": "Pro",
    "status": "active",
    "cycle": "monthly",
    "renews_or_ends_at": "2026-11-14T00:00:00.000Z"
  }
}

إنشاء فيديو

POST/api/v1/videos

نص إلى فيديو، صورة إلى فيديو (إطار بداية وخيارياً إطار نهاية) أو مرجع إلى فيديو (صور، مقاطع وصوت توجه النتيجة). يتم اختيار الوضع من المدخلات عند تركه فارغًا.

المعلمات

modelstring
مطلوبمعرف النموذج من نقطة نهاية النماذج.
promptstring
مطلوبما الذي يجب أن يحدث في المقطع. اختياري للفيديو من صورة، حيث يقود إطار البداية.
modestring
اختيارينص إلى فيديو، صورة إلى فيديو أو مرجع إلى فيديو. يُختار من مدخلاتك عند تركه فارغًا.
durationinteger
اختياريمدة المقطع بالثواني. يجب أن تكون من مدد النموذج، وإلا يُستخدم الافتراضي.
resolutionstring
اختياريدقة الإخراج مثل 720p أو 1080p، من قائمة النموذج.
aspect_ratiostring
اختياري16:9، 9:16، 1:1، 4:3، 3:4 أو 21:9، من قائمة النماذج. الافتراضي 16:9.
audioboolean
اختياريإنشاء مسار صوتي مع حوار وتأثيرات وأجواء على النماذج التي تدعم ذلك. يضيف 20 ائتمانات. الافتراضي خطأ.
image_urlstring (URL)
اختياريالإطار الابتدائي لتحويل الصورة إلى فيديو.
end_image_urlstring (URL)
اختياريالإطار النهائي، على النماذج التي تدعم الإطار الأول والأخير.
reference_image_urlsstring[]
اختياريصور مرجعية لتحويل المرجع إلى فيديو، حتى حد النموذج.
reference_video_urlsstring[]
اختياريمقاطع مرجعية لتحويل المرجع إلى فيديو، حتى حد النموذج.
reference_audio_urlsstring[]
اختياريصوت يوجه المسار الصوتي، حتى حد النموذج.
countinteger
اختياريعدد مقاطع الفيديو التي سيتم إنشاؤها من نفس الطلب، من 1 إلى 4. كل واحد مهمة منفصلة ويتم تحصيل رسومها بشكل منفصل.
seedinteger
اختياريبذرة ثابتة لنتائج قابلة للتكرار. كل عنصر إضافي في الدفعة يحصل على البذرة التالية.

طلب

curl -X POST https://novamotions.com/api/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-pro",
    "prompt": "لقطة دوللي بطيئة عبر شارع نيون ممطر ليلاً، انعكاسات على أسفلت مبلل، سينمائي",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

استجابة

JSON

{
  "tasks": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "status": "queued",
      "credits": 44,
      "url": "https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2"
    }
  ],
  "credits_charged": 44,
  "balance": 1131
}

إنشاء صور

POST/api/v1/images

نص إلى صورة، أو تعديل صورة موجودة بوصف. اطلب حتى أربع صور لكل طلب، كل واحدة مهمة مستقلة.

المعلمات

modelstring
مطلوبمعرف النموذج من نقطة نهاية النماذج.
promptstring
مطلوبما يجب أن تظهره الصورة، أو كيفية تعديل الصورة التي تقدمها.
modestring
اختياريتحويل نص إلى صورة أو تعديل صورة. يتم اختياره من مدخلاتك عند عدم التحديد.
resolutionstring
اختياري1K، 2K أو 4K، من قائمة النماذج.
aspect_ratiostring
اختيارينسبة العرض إلى الارتفاع من قائمة النماذج، بما في ذلك التلقائي على النماذج التي تدعمه.
image_urlstring (URL)
اختياريالصورة التي سيتم تعديلها. مطلوب لتعديل الصورة.
reference_image_urlsstring[]
اختياريصور مرجعية إضافية للتعديل، حتى حد النموذج.
countinteger
اختياريعدد الصور لكل طلب، من 1 إلى 4. كل واحدة مهمة منفصلة.
seedinteger
اختياريبذرة ثابتة لنتائج قابلة للتكرار. كل عنصر إضافي في الدفعة يحصل على البذرة التالية.

طلب

curl -X POST https://novamotions.com/api/v1/images \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "صورة منتج استوديو لفنجان قهوة خزفي على خشب البلوط، ضوء ناعم من النافذة، عمق ميدان ضحل",
    "resolution": "1K",
    "aspect_ratio": "1:1",
    "count": 1
  }'

استجابة

JSON

{
  "tasks": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "status": "queued",
      "credits": 3,
      "url": "https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2"
    }
  ],
  "credits_charged": 3,
  "balance": 1172
}

إنشاء أغنية

POST/api/v1/music

أغنية كاملة من وصف، مع كلماتك الخاصة أو كآلة موسيقية فقط.

المعلمات

modelstring
مطلوبمعرف النموذج من نقطة نهاية النماذج.
promptstring
مطلوبالنوع، المزاج، الآلات والإيقاع للأغنية.
durationinteger
اختياريمدة الأغنية بالثواني، من مدد النموذج.
lyricsstring
اختياريكلمات الأغنية الخاصة بك. اتركها ليكتبها النموذج.
instrumentalboolean
اختياريإنشاء أغنية بدون غناء. الافتراضي خطأ.

طلب

curl -X POST https://novamotions.com/api/v1/music \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai-music",
    "prompt": "هيب هوب لو-فاي دافئ مع بيانو ناعم، طقطقة الفينيل وإيقاع هادئ في وقت متأخر من الليل",
    "duration": 60,
    "instrumental": false
  }'

استجابة

JSON

{
  "tasks": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "status": "queued",
      "credits": 11,
      "url": "https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2"
    }
  ],
  "credits_charged": 11,
  "balance": 1164
}

الحصول على مهمة

GET/api/v1/tasks/{id}

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

طلب

curl https://novamotions.com/api/v1/tasks/cmtask8k2x0001ab7c9d0e1f2 \
  -H "Authorization: Bearer $API_KEY"

استجابة

JSON

{
  "id": "cmtask8k2x0001ab7c9d0e1f2",
  "object": "task",
  "kind": "video",
  "model": "seedance-2-pro",
  "mode": "text-to-video",
  "status": "succeeded",
  "progress": 100,
  "prompt": "لقطة دوللي بطيئة عبر شارع نيون ممطر ليلاً، انعكاسات على أسفلت مبلل، سينمائي",
  "params": {
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "seed": null
  },
  "output_url": "https://novamotions.com/uploads/videos/2026/10/example.mp4",
  "thumbnail_url": "https://novamotions.com/uploads/videos/2026/10/example.jpg",
  "width": 1280,
  "height": 720,
  "duration_seconds": 5,
  "credits": 44,
  "refunded": false,
  "error": null,
  "created_at": "2026-10-18T09:30:00.000Z",
  "completed_at": "2026-10-18T09:31:12.000Z"
}

قائمة المهام

GET/api/v1/tasks

المهام التي أنشأتها عبر API خلال آخر 30 يومًا، الأحدث أولاً، بنفس شكل المهمة الواحدة. مرر next_cursor كـ cursor لتحميل الصفحة التالية.

المعلمات

limitinteger
اختياريعدد النتائج لكل صفحة، من 1 إلى 50. الافتراضي 20.
cursorstring
اختياريقيمة next_cursor من الصفحة السابقة.
statusstring
اختياريالمهام التي تحمل هذه الحالة فقط: في الانتظار، قيد التنفيذ، ناجحة أو فاشلة.

طلب

curl https://novamotions.com/api/v1/tasks?limit=20 \
  -H "Authorization: Bearer $API_KEY"

استجابة

JSON

{
  "object": "list",
  "data": [
    {
      "id": "cmtask8k2x0001ab7c9d0e1f2",
      "object": "task",
      "kind": "video",
      "model": "seedance-2-pro",
      "mode": "text-to-video",
      "status": "succeeded",
      "progress": 100,
      "prompt": "لقطة دوللي بطيئة عبر شارع نيون ممطر ليلاً، انعكاسات على أسفلت مبلل، سينمائي",
      "params": {
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "audio": false,
        "seed": null
      },
      "output_url": "https://novamotions.com/uploads/videos/2026/10/example.mp4",
      "thumbnail_url": "https://novamotions.com/uploads/videos/2026/10/example.jpg",
      "width": 1280,
      "height": 720,
      "duration_seconds": 5,
      "credits": 44,
      "refunded": false,
      "error": null,
      "created_at": "2026-10-18T09:30:00.000Z",
      "completed_at": "2026-10-18T09:31:12.000Z"
    }
  ],
  "next_cursor": null
}

حالات المهام

تنتقل المهمة من في الانتظار إلى قيد التنفيذ وتنتهي كناجحة أو فاشلة. توقف عن الاستعلام عند أي من الحالتين النهائيتين.

queued: تم قبولها وتنتظر فتحة العرض. استمر في الاستعلام.
running: جارٍ العرض الآن. التقدم من 0 إلى 99.
succeeded: تم الانتهاء. تشير output_url و thumbnail_url إلى الملفات النهائية.
failed: انتهت بدون نتيجة. يشرح الخطأ السبب و refunded صحيح، وتمت إعادة الائتمانات إلى رصيدك.

رموز الخطأ

كل خطأ له نفس الشكل. استند إلى الكود وعرّض الرسالة للمستخدم. قد تفشل مهمة تم قبولها لاحقًا، لذا تحقق من حالتها عند الاستعلام.

استجابة الخطأ

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request. Top up or renew your plan, then retry.",
    "needed": 44,
    "balance": 14
  }
}

HTTPالكودالمعنى

400invalid_jsonالنص ليس كائن JSON.
401unauthorizedلا يوجد مفتاح Bearer في رأس التفويض.
401invalid_api_keyالمفتاح غير موجود أو غير صالح.
401key_revokedتم إلغاء المفتاح. أنشئ مفتاحًا جديدًا.
402insufficient_creditsلا توجد ائتمانات كافية لهذا الطلب. الاستجابة تتضمن المطلوب والرصيد.
403plan_limit_exceededالطلب يتجاوز حد التوليد لكل خطة. خفّض المدة أو الدقة.
403account_suspendedالحساب الذي يملك المفتاح موقوف.
403api_disabledواجهة برمجة التطبيقات معطلة حاليًا.
404not_foundالمهمة أو نقطة النهاية غير موجودة في هذا الحساب.
404model_not_foundلا يوجد نموذج بهذا المعرف. تحقق من نقطة نهاية النماذج.
409too_many_runningهذا الحساب لديه 3 مهام قيد التشغيل بالفعل. انتظر حتى تنتهي واحدة.
422invalid_requestحقل مفقود أو من النوع الخطأ. التفاصيل تسرد كل مشكلة.
422wrong_endpointالنموذج ينتمي إلى نقطة نهاية أخرى، مثل نموذج صورة أُرسل إلى الفيديوهات.
422invalid_modeالوضع غير معروف لهذه النقطة النهائية.
422mode_not_supportedالنموذج لا يدعم هذا الوضع.
422prompt_requiredهذا الوضع يحتاج إلى طلب.
422image_requiredهذا الوضع يحتاج إلى image_url.
429rate_limitedطلبات كثيرة جدًا. انتظر عدد الثواني في Retry-After ثم حاول مرة أخرى.
500internal_errorحدث خطأ في جانبنا. حاول مرة أخرى بعد قليل.
503service_busyنحن في أقصى طاقتنا الآن. حاول مرة أخرى بعد دقائق.

الائتمانات والاستردادات

يتم الخصم مرة واحدة عند الإرسال

كل مهمة تكلف نفس تكلفة الإعدادات نفسها في الاستوديو. تعيد استجابة الإرسال credits_charged ورصيدك الجديد. الصوت على الفيديو يضيف 20 ائتمانات.

استرداد كامل للمهام الفاشلة

إذا فشلت مهمة لأي سبب، تعود كل ائتماناتها إلى المجمعات التي أتت منها وتظهر المهمة refunded كصحيح. لا يوجد شيء للمطالبة به.

تطبق حدود الخطة

ينطبق حد التوليد لكل خطة على مهام API أيضًا. تُستهلك الائتمانات التي تنتهي صلاحيتها أولاً أولاً، وتُستهلك ائتمانات التعبئة أخيرًا.

حدود المعدل

الحدود تُحسب لكل مفتاح خلال دقيقة متجددة. عند تجاوز الحد تحصل على HTTP 429 مع رأس Retry-After بالثواني. كل استجابة تحمل رؤوس X-RateLimit لتتمكن من التباطؤ قبل الوصول للحد.

إرسال: 30 في الدقيقة; إنشاء فيديوهات، صور وأغاني.
قراءة: 120 في الدقيقة; المهام، الرصيد والنماذج. تُحسب منفصلة عن الإرسال.
التشغيل المتزامن: 3; عدد المهام التي يتم عرضها في نفس الوقت لكل حساب.

رؤوس حد المعدل

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

النماذج

النماذج التي يمكنك استخدامها اليوم مع معرفاتها وأدنى سعر. نقطة نهاية النماذج تعيد نفس القائمة مع كل الخيارات.

النموذجSlugالنوعمن

Seedance 2.5seedance-2-5فيديو45 ائتمانات
Seedance 2.0 Proseedance-2-proفيديو35 ائتمانات
Seedance 2.0 Miniseedance-2-miniفيديو24 ائتمانات
Wan 3.0wan-3فيديو46 ائتمانات
MiniMax H3minimax-h3فيديو30 ائتمانات
Kling 3kling-3فيديو30 ائتمانات
Seedance 1.5 Proseedance-1-5-proفيديو31 ائتمانات
Seedance 1.0seedance-1فيديو32 ائتمانات
Kling O3kling-o3فيديو46 ائتمانات
Kling 2.6kling-2-6فيديو41 ائتمانات
Wan 2.7wan-2-7فيديو35 ائتمانات
Wanwanفيديو32 ائتمانات
Grokgrok-videoفيديو47 ائتمانات
Veo 3veo-3فيديو42 ائتمانات
GPT Image 2.5gpt-image-2-5صورة4 ائتمانات
GPT Image 2gpt-image-2صورة3 ائتمانات
Seedream 5 Proseedream-5-proصورة4 ائتمانات
Seedream 5seedream-5صورة3 ائتمانات
Nano Banana Pronano-banana-proصورة5 ائتمانات
Nano Banana 2nano-banana-2صورة3 ائتمانات
Nano Banana 2 Litenano-banana-2-liteصورة2 ائتمانات
AI Musicai-musicموسيقى6 ائتمانات

هل أنت مستعد للإنشاء؟

أنشئ مفتاحًا في حسابك وأرسل طلبك الأول خلال دقيقة.

إنشاء مفتاح API