إنشاء الوسائط (الفيديو والصور والموسيقى)

يتيح NordRouter إنشاء الصور والفيديو والموسيقى، باستخدام مفتاح sk-nr-… نفسه والرصيد نفسه المستخدمَين مع النماذج النصية. تُحتسب التكلفة عند الاستخدام، دون رموز أو باقات.

الطلبات من الخادم فقط، وليس من المتصفح

لا يمكن الاتصال بـ/media/* مباشرةً من المتصفح؛ إذ سيفشل الطلب في اجتياز فحص CORS وينتهي بالخطأ Failed to fetch.

هذا مقصود. يتطلب المسار مفتاحك في ترويسة Authorization، وكل ما يصل إلى المتصفح يكون مرئيًا لأي شخص يفتح أدوات المطوّر؛ فيتسرّب المفتاح ويبدأ الآخرون بالإنفاق من رصيدك. لا تحميك أي ترويسات في fetch من ذلك.

الطريقة الصحيحة:

المتصفح → خادمك (المفتاح محفوظ هنا) → nordrouter.com

يُقدَّم الملف الجاهز برابط عادي، ويمكن إدراجه مباشرةً في <img src> أو <video src> على الصفحة، دون الحاجة إلى أي إعداد.

آلية العمل

تتم عملية الإنشاء بشكل غير متزامن (يستغرق إنشاء الفيديو والموسيقى من بضع ثوانٍ إلى دقيقتين):

1. أنشئ مهمة — أرسل POST /media/generate مع النموذج والمعلمات.
2. انتظر النتيجة — استعلم عن GET /media/job/:id إلى أن تصبح قيمة status هي done.
3. نزّل الملف — عبر result_url (رابط على nordrouter.com).

1. إنشاء مهمة

curl https://nordrouter.com/media/generate \
  -H "Authorization: Bearer sk-nr-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image/nano-banana-2",
    "input": { "prompt": "уютная хижина в зимнем лесу, акварель", "resolution": "2k" }
  }'

الاستجابة:

{ "id": "beefb531-…", "model": "image/nano-banana-2", "status": "processing",
  "poll": "https://nordrouter.com/media/job/beefb531-…" }

تأتي الأخطاء دائمًا بالتنسيق نفسه: { "error": "نص واضح", "code": "missing_param" }. يسهل استخدام code للتفرّع في الشيفرة (invalid_input, missing_param, unknown_model, insufficient_balance, rate_limited, no_auth…)، أما error فهو موجّه للمستخدم.

2. انتظار النتيجة

curl https://nordrouter.com/media/job/beefb531-…

{ "id": "beefb531-…", "status": "done",
  "result_url": "https://nordrouter.com/media/file/beefb531-…",
  "cost_usd": 0.052, "error": null }

status: processing → done (أو failed). الملف الجاهز متاح عبر result_url.

🎵 ينشئ Suno مقطعين لكل مهمة: الأول في result_url، والثاني في result_url_2 (بالصيغة نفسها). السعر محسوب للمهمة كاملةً، ويشمل المقطعين.

خطافات الويب (بديلًا عن الاستطلاع)

إذا لم ترغب في الاستعلام، أرسل الحقل callback_url ضمن POST /media/generate، وسنرسل النتيجة تلقائيًا عبر طلب POST عند اكتمال المهمة:

curl https://nordrouter.com/media/generate \
  -H "Authorization: Bearer sk-nr-YOUR-KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "image/nano-banana-2",
    "input": { "prompt": "…" },
    "callback_url": "https://your-server.com/webhooks/nordrouter",
    "callback_secret": "ваш-секрет"
  }'

عند انتقال المهمة إلى done أو failed، سيصل إلى callback_url طلب POST يتضمن الجسم نفسه الذي يعيده GET /media/job/:id، إضافةً إلى الحقل event:

{ "event": "media.completed", "id": "beefb531-…", "status": "done",
  "result_url": "https://nordrouter.com/media/file/beefb531-…", "cost_usd": 0.052, "error": null }

قيمة event: media.completed أو media.failed.

التحقق من التوقيع. إذا عيّنت callback_secret، فستصل في الترويسة X-NR-Signature قيمة sha256=<hmac>، وهي HMAC-SHA256 محسوبة من جسم الطلب باستخدام السر الخاص بك. تحقّق منها للتأكد من أن الطلب صادر عنا:

import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-NR-Signature"])

المتطلبات والموثوقية:

• يجب أن يكون callback_url عنوانًا عامًا يستخدم https:// فقط (تُرفض عناوين IP الداخلية أو الخاصة مع خطأ 400).
• تُجرى حتى 4 محاولات للتسليم مع فواصل زمنية متزايدة؛ أعد استجابة 2xx، وإلا فسنحاول مجددًا.
• لا يُغني خطاف الويب عن الاستطلاع؛ يمكنك الجمع بينهما أو استخدام GET /media/job/:id كخيار احتياطي.

مزيد من التفاصيل

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

3. قائمة النماذج والأسعار

يعرض GET /media/models النماذج المتاحة ومعلماتها وتقدير تكلفتها:

{ "models": [
    { "id": "image/nano-banana-2", "type": "image",
      "fields": [ {"name":"prompt","type":"textarea"}, {"name":"resolution","type":"select","options":["1k","2k","4k"]},
                  {"name":"safety_filter","type":"bool","default":true} ],
      "est_usd": 0.052 }
  ], "retention_days": 14 }

الدليل الكامل

تجد جميع النماذج ومعلمات input والأسعار في صفحة الوسائط: جميع النماذج والفوترة.

النماذج

يتوفر 95 نموذجًا. القائمة الكاملة والمحدّثة دائمًا، مع المعلمات والأسعار، موجودة في GET /media/models. العائلات الرئيسية:

النوع	العائلة	الأوضاع	السعر التقريبي
🖼 الصور	Nano Banana / 2 / Pro (image/nano-banana*)	نص→صورة، تعديل، حتى 4K	ابتداءً من $0.025
🖼	Imagen 4 Fast / Ultra (image/imagen4*)	نص→صورة	ابتداءً من $0.025
🖼	GPT Image 1.5 / 2 (image/gpt-image-*)	نص→صورة، تعديل، حتى 4K	ابتداءً من $0.025
🖼	Flux 2 Pro / Flex (image/flux2-*)	نص→صورة، تعديل	ابتداءً من $0.03
🖼	Seedream v4 / 4.5 / 5 Lite (image/seedream-*)	نص→صورة، تعديل	ابتداءً من $0.04
🖼	Ideogram v3 / Character (image/ideogram-*)	نص، ريمكس، شخصية	ابتداءً من $0.02
🖼	Qwen / Wan Image / Grok / Z-Image	نص→صورة، تعديل	ابتداءً من $0.01
🛠 الأدوات	Topaz / Recraft (image/*upscale*, image/recraft-remove-bg)	ترقية الدقة حتى 8K، إزالة الخلفية	ابتداءً من $0.01
🎬 الفيديو	Veo 3.1 Lite / Fast / Quality (video/veo-3.1-*)	نص/صورة→فيديو	ابتداءً من $0.19
🎬	Kling 2.1 → 3.0 (video/kling-*)	نص/صورة→فيديو، حركة، صور رمزية، حتى 4K و15 ثانية	ابتداءً من $0.16
🎬	Wan 2.2 → 2.7 (video/wan-*)	نص/صورة/فيديو→فيديو، تحويل الكلام إلى فيديو	ابتداءً من $0.25
🎬	Seedance 1.5 / 2 / Fast / Mini (video/seedance-*)	نص/صورة→فيديو، حتى 4K، صوت	ابتداءً من $0.06
🎬	Hailuo 02 / 2.3 (video/hailuo-*)	نص/صورة→فيديو	ابتداءً من $0.08
🎬	HappyHorse 1.0 / 1.1 (video/happyhorse-*)	نص/صورة/مرجع→فيديو، تعديل الفيديو	ابتداءً من $0.70
🎬	Grok Video / 1.5 (video/grok-*)	نص/صورة→فيديو، حتى 30 ثانية	ابتداءً من $0.06
🎬	Gemini Omni (video/gemini-omni)	فيديو مع صوت، حتى 4K	ابتداءً من $0.39
🗣 الصور الرمزية	Kling Avatar, OmniHuman, InfiniteTalk, Lip Sync	صورة+صوت→فيديو ناطق	ابتداءً من $0.19
🎵 الموسيقى	Suno V6 / V6 Wild / V6 Mini (music/suno-*)	نص/أسلوب→مقطوعتان، غلاف، متابعة، غناء، مسارات، أصوات	~$0.08
🎙 التعليق الصوتي	ElevenLabs Turbo / Multilingual (audio/elevenlabs-*)	نص→كلام، عزل الصوت	ابتداءً من $0.04 / 1000 حرف

المعلمات

تختلف المعلمات حسب النموذج. القائمة الدقيقة موجودة في /media/models (الحقل fields: الاسم، النوع، الخيارات، القيمة الافتراضية). الأسماء بتنسيق موحّد (snake_case)، والقيم بأحرف صغيرة. المعلمات العامة:

• prompt — الوصف (لجميع النماذج التوليدية).
• resolution — 1k/2k/4k (للصور) أو 480p/720p/768p/1080p/4k (للفيديو). يعتمد السعر على الدقة.
• aspect_ratio — 1:1 و16:9 و9:16 وغيرها؛ لدى النماذج التي تتيح اختيار الحجم الخيار 1:1-hd.
• duration — مدة الفيديو بالثواني (معظم النماذج تدعم 5/10، وKling 3.0 وWan 2.7 حتى 15، وGrok حتى 30). تُحتسب تكلفة الفيديو بالثانية.
• audio — المسار الصوتي في الفيديو (true/false). وجود الصوت يزيد التكلفة، ويأخذ تقدير /media/estimate ذلك في الحسبان.
• mode / quality / render_mode — مستوى الجودة (Kling 3.0: standard/pro/4k، وGPT Image: medium/high، وIdeogram: fast/balanced/quality).
• safety_filter — فلتر المحتوى +18 (مفعّل افتراضيًا).
• enhance_prompt — يوسّع النموذج وصف المطالبة تلقائيًا (Qwen، Flux 3).
• file_format — تنسيق الملف (png/jpeg للصور، وglb/obj/fbx/stl/usdz للوسائط ثلاثية الأبعاد).
• image — صورة الإدخال (للتعديل أو للتحويل من صورة إلى فيديو؛ أرسل رابطًا مباشرًا أو ارفعها عبر /media/upload).
• video_url / audio_url — فيديو/صوت الإدخال (لتعديل الفيديو، ومزامنة الشفاه، والصور الرمزية).

الموسيقى: title وstyle وinstrumental وversion (v6، v6-wild، v6-mini) وadvanced (ضبط دقيق: عنوانك وأسلوبك ومدة duration) وexclude_styles وvocal (female/male) وcontinue_from (الثانية التي تبدأ منها المتابعة). للأصوات: loop وbpm وtonality. تقسيم المسارات: mode (vocals، stems، track) وtrack (المسار المطلوب استخراجه). عناصر ضبط الأسلوب الدقيقة: style_weight وweirdness وaudio_weight (من 0 إلى 1).

التعليق الصوتي: text وvoice (اسم قصير للصوت من options، مثل james وbella وZephyr) وspeed. في نماذج Gemini: style وpace وaccent وvoice_description وscene وtemperature. حوار بصوتين:

{ "model": "audio/gemini-3.1-flash-tts",
  "input": {
    "voices": [ { "voice": "Kore", "style": "newscaster" }, { "voice": "Puck", "pace": "fast" } ],
    "dialogue": [ { "speaker": 1, "text": "مرحبًا! ضيفنا اليوم هو…" }, { "speaker": 2, "text": "شكرًا على الاستضافة." } ]
  } }

يعرض POST /media/estimate السعر الدقيق للإعداد المحدد قبل التشغيل، باستخدام model وinput نفسيهما.

لا تزال أسماء المعلمات السابقة مدعومة

في 19 أكتوبر 2026، وُحّدت أسماء المعلمات وقيمها (snake_case، والقيم بأحرف صغيرة). إذا كان التكامل لديك يرسل أسماء وقيمًا من إصدار سابق من الوثائق، فلا حاجة إلى إجراء أي تغييرات: يقبلها الخادم أيضًا، والنتيجة والسعر لا يتغيران. يعرض /media/models وهذه الوثائق الأسماء الجديدة فقط.

🧊 نماذج ثلاثية الأبعاد

إنشاء نماذج ثلاثية الأبعاد من نص أو صورة. تكون النتيجة GLB (وكذلك OBJ وFBX وSTL وUSDZ وUSD بتنسيق 3MF لبعض النماذج)، بالإضافة إلى صورة معاينة: تتضمن المهمة عدة ملفات، لكل منها امتداده الخاص.

طريقة الاستدعاء مماثلة لبقية الوسائط: POST /media/generate والاستعلام عن الحالة عبر GET /media/job/{id}.

curl -X POST https://nordrouter.com/media/generate   -H "Authorization: Bearer $NR_KEY" -H "Content-Type: application/json"   -d '{"model":"3d/tripo-text","input":{"prompt":"كوب خزفي بطلاء زجاجي غير لامع"}}'

المعرّف	المدخلات	السعر التقريبي	الميزات
3d/tripo-text, 3d/tripo-image	نص، صورة	يبدأ من $0.31	الأقل تكلفة، شبكة رباعية الأضلاع، PBR
3d/hunyuan-rapid-text, -image	نص، صورة	يبدأ من $0.43	سريع، 5 تنسيقات ملفات
3d/seed3d-image	صورة	يبدأ من $0.50	GLB، OBJ، USD، USDZ
3d/hunyuan-pro-text, -image	نص، صورة	يبدأ من $0.71	حتى 1.5 مليون مضلع
3d/meshy-text, -image, -multi-image	نص، صورة، حتى 4 زوايا	يبدأ من $0.94	خامات حتى 8K، وضعية للشخصية

الصورة كخامة. تقبل نماذج 3d/meshy-* صورة منفصلة (texture_photo) أو وصفًا نصيًا للمادة (texture_text)، بحيث تُحدَّد الخامة بمعزل عن الشكل الهندسي. يقبل 3d/meshy-multi-image حتى أربع زوايا للعنصر نفسه، ما يساعد على إنشاء شكل هندسي أدق.

لا يُعرف السعر إلا بعد التوليد

تُحتسب تكلفة إنشاء النماذج ثلاثية الأبعاد بحسب الموارد المستخدمة فعليًا، لذلك لا يُعرف المبلغ الدقيق إلا بعد إتمام النموذج. نحجز الحد الأقصى للتكلفة، وعند اكتمال المعالجة نخصم المبلغ الفعلي ونعيد الفرق. يظهر المبلغ النهائي دائمًا في الحقل cost_usd.

في الاستوديو، تُعلَّم هذه النماذج بشارة، ولا يبدأ التوليد إلا بعد موافقتك.

تستغرق وقتًا طويلًا. يستغرق إنشاء النماذج ثلاثية الأبعاد من نصف دقيقة إلى عدة دقائق، أي أطول من إنشاء صورة أو مقطع فيديو قصير. ليس عليك إبقاء المهمة مفتوحة: تُحفَظ الحالة، وتتوفر إشعارات الويب هوك.

التكلفة والتخزين

• يُخصم المبلغ من رصيدك بالدولار الأمريكي وفق التكلفة الفعلية للتوليد؛ ويمكن الاطلاع على المبلغ الدقيق في cost_usd بعد اكتمال العملية.
• لا تُحتسب تكلفة عمليات التوليد غير الناجحة؛ ويُعاد المبلغ المحجوز تلقائيًا.
• تُخزَّن الملفات على خوادمنا لفترة محدودة (راجع retention_days في /media/models)؛ نزّلها للاحتفاظ بها.