تولید رسانه (ویدئو، تصویر، موسیقی)

NordRouter می‌تواند تصویر، ویدئو و موسیقی تولید کند — با همان کلید sk-nr-… و از همان موجودی مدل‌های متنی. پرداخت به‌ازای هر تولید است، بدون توکن و بسته.

درخواست‌ها فقط از بک‌اند، نه از مرورگر

ارسال درخواست مستقیم به /media/* از مرورگر مجاز نیست — درخواست از بررسی CORS عبور نمی‌کند و با خطای Failed to fetch متوقف می‌شود.

این محدودیت عمدی است. این endpoint به کلید شما در هدر 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 برسد، یک درخواست POST به callback_url ارسال می‌شود که بدنهٔ آن همان پاسخ 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-*)	متن/سبک→2 قطعه، کاور، ادامه، آواز، ترک‌ها، صداها	~$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 برای 3D).
• 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 و این مستندات، فقط نام‌ها و مقادیر جدید آمده‌اند.

🧊 مدل‌های 3D

تولید 3D از متن یا عکس. خروجی 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	سریع، ۵ قالب فایل
3d/seed3d-image	عکس	از $0.50	GLB، OBJ، USD، USDZ
3d/hunyuan-pro-text, -image	متن، عکس	از $0.71	تا ۱٫۵ میلیون چندضلعی
3d/meshy-text, -image, -multi-image	متن، عکس، تا ۴ زاویهٔ دید	از $0.94	بافت تا 8K، ژست شخصیت

عکس به‌عنوان بافت. مدل‌های 3d/meshy-* یک تصویر جداگانه (texture_photo) یا توضیح متنیِ جنس ماده (texture_text) می‌پذیرند؛ بافت مستقل از هندسه تعیین می‌شود. 3d/meshy-multi-image تا چهار زاویهٔ دید از یک شیء را می‌گیرد و به این ترتیب هندسه دقیق‌تر می‌شود.

قیمت فقط پس از تولید مشخص می‌شود

هزینهٔ 3D بر اساس منابع مصرف‌شده محاسبه می‌شود؛ بنابراین مبلغ دقیق پس از محاسبهٔ مدل مشخص خواهد شد. حداکثر هزینهٔ ممکن را رزرو می‌کنیم و پس از آماده‌شدن محاسبه، مبلغ واقعی را کسر می‌کنیم و مابه‌التفاوت را بازمی‌گردانیم. مبلغ نهایی همیشه در فیلد cost_usd قابل مشاهده است.

در استودیو، این مدل‌ها با برچسب مشخص شده‌اند و تولید فقط پس از موافقت شما آغاز می‌شود.

زمان‌بر است. محاسبهٔ 3D از نیم دقیقه تا چند دقیقه طول می‌کشد؛ بیشتر از تولید تصویر یا ویدیوی کوتاه. لازم نیست صفحهٔ کار را باز نگه دارید: وضعیت ذخیره می‌شود و وب‌هوک هم در دسترس است.

هزینه و نگه‌داری

• مبلغ بر اساس هزینهٔ واقعی تولید از موجودی USD شما کسر می‌شود؛ مبلغ دقیق پس از اتمام در cost_usd قابل مشاهده است.
• تولیدهای ناموفق هزینه‌ای ندارند؛ مبلغ رزروشده به‌طور خودکار بازگردانده می‌شود.
• فایل‌ها برای مدت محدودی در سرورهای ما نگه‌داری می‌شوند (به retention_days در /media/models مراجعه کنید)؛ برای نگه‌داری فایل‌ها را دانلود کنید.