Генерація медіа (відео, зображення, музика)

NordRouter уміє генерувати зображення, відео та музику — з тим самим ключем sk-nr-… і з того самого балансу, що й текстові моделі. Оплата за фактом, жодних токенів і пакетів.

Запити лише з бекенду, не з браузера

Звертатися до /media/* безпосередньо з браузера не можна — запит не пройде перевірку CORS і перерветься з Failed to fetch.

Це зроблено навмисно. Ендпоінт вимагає ваш ключ у заголовку Authorization, а все, що потрапляє в браузер, видно будь-кому, хто відкриє інструменти розробника: ключ витече, і сторонні почнуть витрачати кошти з вашого балансу. Жодні заголовки у fetch від цього не захищають.

Правильна схема:

браузер → ваш сервер (ключ зберігається тут) → nordrouter.com

Готовий файл при цьому надається за звичайним посиланням — його можна вставляти прямо в <img src> або <video src> на сторінці, для цього нічого налаштовувати не потрібно.

Як це працює

Генерація асинхронна (відео та музика займають від секунд до кількох хвилин):

Створюєте задачу — POST /media/generate з моделлю та параметрами.
Чекаєте на результат — опитуєте GET /media/job/:id, доки status не стане done.
Забираєте файл — за result_url (посилання на nordrouter.com).

1. Створити задачу

bash

curl https://nordrouter.com/media/generate \
  -H "Authorization: Bearer sk-nr-ВАШ-КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image/nano-banana-2",
    "input": { "prompt": "затишна хатина в зимовому лісі, акварель", "resolution": "2k" }
  }'

Відповідь:

json

{ "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. Дочекатися результату

bash

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

json

{ "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 (той самий формат посилання). Ціна — за всю задачу, обидва треки вже включені.

Вебхуки (замість опитування)

Не хочете опитувати — передайте в POST /media/generate поле callback_url, і ми самі надішлемо результат POST-запитом, коли задача завершиться:

bash

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

Коли задача перейде в done/failed, на callback_url надійде POST із тим самим тілом, яке повертає GET /media/job/:id, плюс поле event:

json

{ "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 від тіла запиту з вашим секретом. Звірте, щоб переконатися, що запит від нас:

python

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 повертає доступні моделі, їхні параметри та оцінку вартості:

json

{ "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-*`)	текст/фото→відео, motion, аватари, до 4K і 15с	від $0.16
🎬	Wan 2.2 → 2.7 (`video/wan-*`)	текст/фото/відео→відео, speech-to-video	від $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 — вхідні відео/аудіо (video-edit, ліпсинк, аватари).

Музика: 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. Діалог двох голосів:

json

{ "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}.

bash

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":"керамічна чашка, матова глазур"}}'

id	із чого	≈ ціна	особливості
`3d/tripo-text`, `3d/tripo-image`	текст, фото	від $0.31	найдешевші, quad-сітка, 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 приймає до чотирьох ракурсів одного предмета: так геометрія виходить точнішою.

Ціна відома лише після генерації

3D тарифікується за фактично витраченими ресурсами, тому точна сума стає відома після того, як модель згенеровано. Ми резервуємо максимально можливу вартість, а коли розрахунок буде готовий — списуємо фактичну й повертаємо різницю. Підсумкова сума завжди відображається в полі cost_usd.

У студії такі моделі позначені плашкою, і генерація починається лише після вашої згоди.

Це довго. Генерація 3D триває від пів хвилини до кількох хвилин — довше, ніж зображення чи короткого відео. Завдання можна не тримати відкритим: статус зберігається, є вебхуки.

Вартість і зберігання

Кошти списуються з вашого USD-балансу за фактичною вартістю генерації — точну суму видно в cost_usd після завершення.
Невдалі генерації не тарифікуються — резерв повертається автоматично.
Файли зберігаються на наших серверах обмежений час (див. retention_days у /media/models) — завантажте, щоб зберегти.

Генерація медіа (відео, зображення, музика) ​

Як це працює ​

1. Створити задачу ​

2. Дочекатися результату ​

Вебхуки (замість опитування) ​

3. Список моделей і цін ​

Моделі ​

Параметри ​

🧊 3D-моделі ​

Вартість і зберігання ​

Генерація медіа (відео, зображення, музика)

Як це працює

1. Створити задачу

2. Дочекатися результату

Вебхуки (замість опитування)

3. Список моделей і цін

Моделі

Параметри

🧊 3D-моделі

Вартість і зберігання