Generowanie mediów (wideo, obrazy, muzyka)

NordRouter potrafi generować obrazy, wideo i muzykę — z tym samym kluczem sk-nr-… i z tego samego salda co modele tekstowe. Płacisz za wykonaną generację, bez tokenów i pakietów.

Żądania tylko z backendu, nie z przeglądarki

Nie można wysyłać żądań do /media/* bezpośrednio z przeglądarki — żądanie nie przejdzie weryfikacji CORS i zakończy się błędem Failed to fetch.

To celowe działanie. Endpoint wymaga klucza w nagłówku Authorization, a wszystko, co trafia do przeglądarki, jest widoczne dla każdego, kto otworzy narzędzia deweloperskie: klucz wycieknie, a inne osoby zaczną wydawać środki z Twojego salda. Żadne nagłówki w fetch przed tym nie chronią.

Prawidłowy schemat:

przeglądarka → Twój serwer (tutaj przechowywany jest klucz) → nordrouter.com

Gotowy plik jest udostępniany pod zwykłym linkiem — możesz go wstawić bezpośrednio do <img src> lub <video src> na stronie, bez dodatkowej konfiguracji.

Jak to działa

Generowanie jest asynchroniczne (wideo i muzyka zajmują od kilku sekund do paru minut):

Tworzysz zadanie — POST /media/generate z modelem i parametrami.
Czekasz na wynik — odpytujesz GET /media/job/:id, aż status zmieni się na done.
Pobierasz plik — przez result_url (link do nordrouter.com).

1. Utwórz zadanie

bash

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": "przytulna chatka w zimowym lesie, akwarela", "resolution": "2k" }
  }'

Odpowiedź:

json

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

Błąd ma zawsze ten sam format: { "error": "понятный текст", "code": "missing_param" }. Pole code ułatwia obsługę różnych przypadków w kodzie (invalid_input, missing_param, unknown_model, insufficient_balance, rate_limited, no_auth…), a error zawiera komunikat dla człowieka.

2. Poczekaj na wynik

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 (lub failed). Gotowy plik jest dostępny pod result_url.

🎵 Suno generuje dwa utwory w ramach jednego zadania: pierwszy jest dostępny pod result_url, drugi pod result_url_2 (ten sam format linku). Cena dotyczy całego zadania i obejmuje oba utwory.

Webhooki (zamiast odpytywania)

Jeśli nie chcesz odpytywać o wynik, przekaż pole callback_url w POST /media/generate, a sami wyślemy wynik żądaniem POST po zakończeniu zadania:

bash

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": "ваш-секрет"
  }'

Gdy zadanie przejdzie do stanu done/failed, na callback_url zostanie wysłany POST z taką samą treścią, jaką zwraca GET /media/job/:id, oraz dodatkowym polem 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 lub media.failed.

Weryfikacja podpisu. Jeśli ustawisz callback_secret, nagłówek X-NR-Signature będzie zawierał sha256=<hmac> — HMAC-SHA256 obliczony z treści żądania przy użyciu Twojego sekretu. Porównaj podpisy, aby upewnić się, że żądanie pochodzi od nas:

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"])

Wymagania i niezawodność:

callback_url — tylko https:// i wyłącznie adres publiczny (wewnętrzne/prywatne adresy IP są odrzucane z błędem 400).
Do 4 prób dostarczenia z rosnącymi odstępami; odpowiadaj kodem 2xx, w przeciwnym razie ponowimy próbę.
Webhook nie wyklucza odpytywania — możesz łączyć oba mechanizmy lub używać GET /media/job/:id jako rozwiązania zapasowego.

Więcej informacji

Cykl życia zadania, weryfikacja podpisu z przykładami i niezawodność dostarczania — na stronie Zadania i webhooki.

3. Lista modeli i cen

GET /media/models zwraca dostępne modele, ich parametry i szacunkowy koszt:

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 }

Pełna dokumentacja

Wszystkie modele z parametrami input i cenami — na stronie Media: wszystkie modele i rozliczenia.

Modele

Dostępnych jest 95 modeli — pełna, aktualna lista wraz z parametrami i cenami jest zawsze dostępna w GET /media/models. Główne rodziny:

Typ	Rodzina	Tryby	≈ cena
🖼 Obrazy	Nano Banana / 2 / Pro (`image/nano-banana*`)	tekst→obraz, edycja, do 4K	od $0.025
🖼	Imagen 4 Fast / Ultra (`image/imagen4*`)	tekst→obraz	od $0.025
🖼	GPT Image 1.5 / 2 (`image/gpt-image-*`)	tekst→obraz, edycja, do 4K	od $0.025
🖼	Flux 2 Pro / Flex (`image/flux2-*`)	tekst→obraz, edycja	od $0.03
🖼	Seedream v4 / 4.5 / 5 Lite (`image/seedream-*`)	tekst→obraz, edycja	od $0.04
🖼	Ideogram v3 / Character (`image/ideogram-*`)	tekst, remiks, postać	od $0.02
🖼	Qwen / Wan Image / Grok / Z-Image	tekst→obraz, edycja	od $0.01
🛠 Narzędzia	Topaz / Recraft (`image/upscale`, `image/recraft-remove-bg`)	skalowanie do 8K, usuwanie tła	od $0.01
🎬 Wideo	Veo 3.1 Lite / Fast / Quality (`video/veo-3.1-*`)	tekst/zdjęcie→wideo	od $0.19
🎬	Kling 2.1 → 3.0 (`video/kling-*`)	tekst/zdjęcie→wideo, ruch, awatary, do 4K i 15 s	od $0.16
🎬	Wan 2.2 → 2.7 (`video/wan-*`)	tekst/zdjęcie/wideo→wideo, speech-to-video	od $0.25
🎬	Seedance 1.5 / 2 / Fast / Mini (`video/seedance-*`)	tekst/zdjęcie→wideo, do 4K, dźwięk	od $0.06
🎬	Hailuo 02 / 2.3 (`video/hailuo-*`)	tekst/zdjęcie→wideo	od $0.08
🎬	HappyHorse 1.0 / 1.1 (`video/happyhorse-*`)	tekst/zdjęcie/referencja→wideo, edycja wideo	od $0.70
🎬	Grok Video / 1.5 (`video/grok-*`)	tekst/zdjęcie→wideo, do 30 s	od $0.06
🎬	Gemini Omni (`video/gemini-omni`)	wideo z dźwiękiem, do 4K	od $0.39
🗣 Awatary	Kling Avatar, OmniHuman, InfiniteTalk, Lip Sync	zdjęcie+audio→wideo z mówiącą postacią	od $0.19
🎵 Muzyka	Suno V6 / V6 Wild / V6 Mini (`music/suno-*`)	tekst/styl→2 utwory, cover, kontynuacja, wokal, ścieżki, dźwięki	~$0.08
🎙 Synteza mowy	ElevenLabs Turbo / Multilingual (`audio/elevenlabs-*`)	tekst→mowa, izolacja głosu	od $0.04 / 1000 znaków

Parametry

Parametry zależą od modelu — dokładna lista znajduje się w /media/models (pole fields: nazwa, typ, warianty, wartość domyślna). Nazwy mają jednolity format (snake_case), a wartości są zapisane małymi literami. Wspólne parametry:

prompt — opis (dla wszystkich modeli generatywnych).
resolution — 1k/2k/4k (obrazy) lub 480p/720p/768p/1080p/4k (wideo). Cena zależy od rozdzielczości.
aspect_ratio — 1:1, 16:9, 9:16 itp.; modele z wyborem rozmiaru obsługują też 1:1-hd.
duration — czas trwania wideo w sekundach (większość modeli obsługuje 5/10, Kling 3.0 i Wan 2.7 — do 15, Grok — do 30). Wideo jest rozliczane za sekundę.
audio — ścieżka dźwiękowa w wideo (true/false). Dźwięk zwiększa cenę — uwzględnia to wycena w /media/estimate.
mode / quality / render_mode — poziom jakości (Kling 3.0: standard/pro/4k, GPT Image: medium/high, Ideogram: fast/balanced/quality).
safety_filter — filtr treści 18+ (domyślnie włączony).
enhance_prompt — model samodzielnie rozwija prompt (Qwen, Flux 3).
file_format — format pliku (png/jpeg dla obrazów, glb/obj/fbx/stl/usdz dla 3D).
image — obraz wejściowy (edycja, zdjęcie→wideo; podaj bezpośredni link lub prześlij plik przez /media/upload).
video_url / audio_url — wejściowe wideo/audio (video-edit, synchronizacja ruchu ust, awatary).

Muzyka: title, style, instrumental, version (v6, v6-wild, v6-mini), advanced (precyzyjna konfiguracja: własny tytuł, styl i czas trwania duration), exclude_styles, vocal (female/male), continue_from (od której sekundy kontynuować); dla dźwięków: loop, bpm, tonality; podział na ścieżki: mode (vocals, stems, track) i track (którą ścieżkę wyodrębnić). Precyzyjne ustawienia stylu: style_weight, weirdness, audio_weight (0…1).

Synteza mowy: text, voice (krótka nazwa głosu z options, np. james, bella, Zephyr), speed; w modelach Gemini: style, pace, accent, voice_description, scene, temperature. Dialog dwóch głosów:

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": "Спасибо, что позвали." } ]
  } }

Dokładną cenę danej konfiguracji przed uruchomieniem pokazuje POST /media/estimate z tymi samymi polami model + input.

Dotychczasowe nazwy parametrów nadal działają

19 października 2026 parametry otrzymały ujednolicone nazwy i wartości (snake_case, wartości zapisane małymi literami). Jeśli integracja przekazuje nazwy i wartości z poprzedniej wersji dokumentacji, nie trzeba nic zmieniać: serwer akceptuje również te wartości, a wynik i cena pozostają takie same. W /media/models i tej dokumentacji używane są tylko nowe nazwy.

🧊 Modele 3D

Generowanie modeli 3D z tekstu lub zdjęcia. Wynikiem jest plik GLB (a także OBJ, FBX, STL, USDZ, USD, 3MF w przypadku różnych modeli) oraz obraz podglądu: w zadaniu pojawi się kilka plików, każdy z innym rozszerzeniem.

Wywołanie wygląda tak samo jak w przypadku pozostałych mediów: POST /media/generate i odpytywanie 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":"ceramiczny kubek, matowa glazura"}}'

id	dane wejściowe	≈ cena	cechy
`3d/tripo-text`, `3d/tripo-image`	tekst, zdjęcie	od $0.31	najtańsze, siatka quad, PBR
`3d/hunyuan-rapid-text`, `-image`	tekst, zdjęcie	od $0.43	szybkie, 5 formatów plików
`3d/seed3d-image`	zdjęcie	od $0.50	GLB, OBJ, USD, USDZ
`3d/hunyuan-pro-text`, `-image`	tekst, zdjęcie	od $0.71	do 1,5 mln wielokątów
`3d/meshy-text`, `-image`, `-multi-image`	tekst, zdjęcie, do 4 ujęć	od $0.94	tekstury do 8K, poza postaci

Zdjęcie jako tekstura. Modele 3d/meshy-* przyjmują osobny obraz (texture_photo) lub opis materiału słowami (texture_text) — tekstura jest definiowana niezależnie od geometrii. 3d/meshy-multi-image przyjmuje do czterech ujęć tego samego obiektu, co pozwala uzyskać dokładniejszą geometrię.

Cena jest znana dopiero po wygenerowaniu

Generowanie 3D jest rozliczane na podstawie faktycznie zużytych zasobów, dlatego dokładna kwota jest znana dopiero po obliczeniu modelu. Rezerwujemy maksymalną możliwą kwotę, a po zakończeniu obliczeń pobieramy właściwą należność i zwracamy różnicę. Końcowa kwota jest zawsze widoczna w polu cost_usd.

W studiu takie modele są oznaczone etykietą, a generowanie rozpoczyna się dopiero po wyrażeniu zgody.

To trwa długo. Generowanie 3D zajmuje od pół minuty do kilku minut — dłużej niż wygenerowanie obrazu lub krótkiego wideo. Nie musisz pozostawiać zadania otwartego: jego status jest zapisywany, dostępne są webhooki.

Koszt i przechowywanie

Opłata jest pobierana z salda w USD według faktycznego kosztu generowania — dokładna kwota jest widoczna w cost_usd po zakończeniu.
Nieudane generowania nie są rozliczane — rezerwacja jest zwracana automatycznie.
Pliki są przechowywane na naszych serwerach przez ograniczony czas (zob. retention_days w /media/models) — pobierz je, aby zachować je na później.

Generowanie mediów (wideo, obrazy, muzyka) ​

Jak to działa ​

1. Utwórz zadanie ​

2. Poczekaj na wynik ​

Webhooki (zamiast odpytywania) ​

3. Lista modeli i cen ​

Modele ​

Parametry ​

🧊 Modele 3D ​

Koszt i przechowywanie ​

Generowanie mediów (wideo, obrazy, muzyka)

Jak to działa

1. Utwórz zadanie

2. Poczekaj na wynik

Webhooki (zamiast odpytywania)

3. Lista modeli i cen

Modele

Parametry

🧊 Modele 3D

Koszt i przechowywanie