Generazione di contenuti multimediali (video, immagini, musica)

NordRouter può generare immagini, video e musica con la stessa chiave sk-nr-… e lo stesso saldo usati per i modelli di testo. Paghi solo per ciò che generi, senza token né pacchetti.

Richieste solo dal backend, non dal browser

Non puoi chiamare direttamente /media/* dal browser: la richiesta non supererà il controllo CORS e terminerà con Failed to fetch.

È una scelta intenzionale. L’endpoint richiede la tua chiave nell’header Authorization, ma tutto ciò che arriva al browser è visibile a chiunque apra gli strumenti per sviluppatori: la chiave verrebbe esposta e altri potrebbero spendere il tuo saldo. Nessun header in fetch può impedirlo.

Schema corretto:

browser → il tuo server (la chiave resta qui) → nordrouter.com

Il file generato viene invece fornito tramite un normale link, che puoi inserire direttamente in <img src> o <video src> sulla pagina, senza configurazioni aggiuntive.

Come funziona

La generazione è asincrona (video e musica richiedono da alcuni secondi a un paio di minuti):

Crea un’attività — POST /media/generate con il modello e i parametri.
Attendi il risultato — interroga GET /media/job/:id finché status non diventa done.
Recupera il file — tramite result_url (un link a nordrouter.com).

1. Crea un’attività

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": "уютная хижина в зимнем лесу, акварель", "resolution": "2k" }
  }'

Risposta:

json

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

Gli errori hanno sempre lo stesso formato: { "error": "testo descrittivo", "code": "missing_param" }. È utile usare code per gestire i casi nel codice (invalid_input, missing_param, unknown_model, insufficient_balance, rate_limited, no_auth…); error è rivolto alle persone.

2. Attendi il risultato

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 (oppure failed). Il file generato è disponibile tramite result_url.

🎵 Suno genera due tracce per attività: la prima è in result_url, la seconda in result_url_2 (stesso formato di link). Il prezzo si applica all’intera attività e include entrambe le tracce.

Webhook (invece del polling)

Se non vuoi interrogare l’endpoint, passa il campo callback_url a POST /media/generate e ti invieremo noi il risultato con una richiesta POST al completamento dell’attività:

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

Quando l’attività passa a done o failed, riceverai una richiesta POST a callback_url con lo stesso corpo restituito da GET /media/job/:id, più il campo 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 oppure media.failed.

Verifica della firma. Se hai impostato callback_secret, nell’header X-NR-Signature riceverai sha256=<hmac> — HMAC-SHA256 del corpo della richiesta, calcolato con il tuo secret. Verifica la firma per accertarti che la richiesta provenga da noi:

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

Requisiti e affidabilità:

callback_url deve usare https:// e avere un indirizzo pubblico (gli IP interni o privati vengono rifiutati con un errore 400).
Effettuiamo fino a 4 tentativi di consegna, con intervalli crescenti; rispondi con 2xx, altrimenti riproveremo.
Il webhook non sostituisce il polling: puoi usare entrambi oppure ricorrere a GET /media/job/:id.

Approfondisci

Il ciclo di vita delle attività, la verifica della firma con esempi e l’affidabilità della consegna sono descritti nella pagina Attività e webhook.

3. Elenco dei modelli e prezzi

GET /media/models restituisce i modelli disponibili, i relativi parametri e una stima dei costi:

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 }

Riferimento completo

Tutti i modelli, con i parametri input e i prezzi, sono elencati nella pagina Media: tutti i modelli e la fatturazione.

Modelli

Sono disponibili 95 modelli — l'elenco completo e aggiornato con parametri e prezzi è sempre disponibile in GET /media/models. Famiglie principali:

Tipo	Famiglia	Modalità	≈ prezzo
🖼 Immagini	Nano Banana / 2 / Pro (`image/nano-banana*`)	testo→immagine, modifica, fino a 4K	da $0.025
🖼	Imagen 4 Fast / Ultra (`image/imagen4*`)	testo→immagine	da $0.025
🖼	GPT Image 1.5 / 2 (`image/gpt-image-*`)	testo→immagine, modifica, fino a 4K	da $0.025
🖼	Flux 2 Pro / Flex (`image/flux2-*`)	testo→immagine, modifica	da $0.03
🖼	Seedream v4 / 4.5 / 5 Lite (`image/seedream-*`)	testo→immagine, modifica	da $0.04
🖼	Ideogram v3 / Character (`image/ideogram-*`)	testo, remix, personaggio	da $0.02
🖼	Qwen / Wan Image / Grok / Z-Image	testo→immagine, modifica	da $0.01
🛠 Utilità	Topaz / Recraft (`image/upscale`, `image/recraft-remove-bg`)	upscaling fino a 8K, rimozione dello sfondo	da $0.01
🎬 Video	Veo 3.1 Lite / Fast / Quality (`video/veo-3.1-*`)	testo/foto→video	da $0.19
🎬	Kling 2.1 → 3.0 (`video/kling-*`)	testo/foto→video, motion, avatar, fino a 4K e 15 s	da $0.16
🎬	Wan 2.2 → 2.7 (`video/wan-*`)	testo/foto/video→video, speech-to-video	da $0.25
🎬	Seedance 1.5 / 2 / Fast / Mini (`video/seedance-*`)	testo/foto→video, fino a 4K, audio	da $0.06
🎬	Hailuo 02 / 2.3 (`video/hailuo-*`)	testo/foto→video	da $0.08
🎬	HappyHorse 1.0 / 1.1 (`video/happyhorse-*`)	testo/foto/riferimento→video, modifica video	da $0.70
🎬	Grok Video / 1.5 (`video/grok-*`)	testo/foto→video, fino a 30 s	da $0.06
🎬	Gemini Omni (`video/gemini-omni`)	video con audio, fino a 4K	da $0.39
🗣 Avatar	Kling Avatar, OmniHuman, InfiniteTalk, Lip Sync	foto+audio→video parlante	da $0.19
🎵 Musica	Suno V6 / V6 Wild / V6 Mini (`music/suno-*`)	testo/stile→2 brani, cover, continuazione, voce, tracce, suoni	~$0.08
🎙 Sintesi vocale	ElevenLabs Turbo / Multilingual (`audio/elevenlabs-*`)	testo→voce, isolamento della voce	da $0.04 / 1000 caratteri

Parametri

I parametri dipendono dal modello — l'elenco esatto è in /media/models (campo fields: nome, tipo, opzioni, valore predefinito). I nomi seguono uno stile uniforme (snake_case), i valori sono in minuscolo. Parametri comuni:

prompt — descrizione (per tutti i modelli generativi).
resolution — 1k/2k/4k (immagini) oppure 480p/720p/768p/1080p/4k (video). Il prezzo dipende dalla risoluzione.
aspect_ratio — 1:1, 16:9, 9:16 ecc.; i modelli che consentono di scegliere le dimensioni offrono 1:1-hd.
duration — durata del video in secondi (per la maggior parte 5/10, per Kling 3.0 e Wan 2.7 fino a 15, per Grok fino a 30). I video vengono fatturati al secondo.
audio — traccia audio nel video (true/false). Con l'audio il costo è maggiore — la stima in /media/estimate ne tiene conto.
mode / quality / render_mode — livello di qualità (Kling 3.0 standard/pro/4k, GPT Image medium/high, Ideogram fast/balanced/quality).
safety_filter — filtro per contenuti 18+ (attivo per impostazione predefinita).
enhance_prompt — il modello arricchisce automaticamente il prompt con maggiori dettagli (Qwen, Flux 3).
file_format — formato del file (png/jpeg per le immagini, glb/obj/fbx/stl/usdz per il 3D).
image — immagine di input (modifica, foto→video; passa un link diretto oppure caricala tramite /media/upload).
video_url / audio_url — video/audio di input (modifica video, sincronizzazione labiale, avatar).

Musica: title, style, instrumental, version (v6, v6-wild, v6-mini), advanced (configurazione dettagliata: titolo, stile e durata duration personalizzati), exclude_styles, vocal (female/male), continue_from (da quale secondo continuare), per i suoni — loop, bpm, tonality; separazione in tracce — mode (vocals, stems, track) e track (quale traccia estrarre). Controlli avanzati dello stile: style_weight, weirdness, audio_weight (0…1).

Sintesi vocale: text, voice (nome breve della voce da options, ad esempio james, bella, Zephyr), speed; per i modelli Gemini — style, pace, accent, voice_description, scene, temperature. Dialogo a due voci:

json

{ "model": "audio/gemini-3.1-flash-tts",
  "input": {
    "voices": [ { "voice": "Kore", "style": "newscaster" }, { "voice": "Puck", "pace": "fast" } ],
    "dialogue": [ { "speaker": 1, "text": "Ciao! Oggi abbiamo come ospite…" }, { "speaker": 2, "text": "Grazie per l'invito." } ]
  } }

Il prezzo esatto di una configurazione specifica prima dell'avvio è indicato da POST /media/estimate con gli stessi model + input.

I vecchi nomi dei parametri funzionano ancora

Il 19 ottobre 2026 i parametri hanno ricevuto nomi e valori uniformi (snake_case, valori in minuscolo). Se la tua integrazione invia nomi e valori della versione precedente della documentazione, non occorre modificare nulla: il server accetta anche quelli, il risultato e il prezzo restano gli stessi. In /media/models e in questa documentazione sono riportati solo quelli nuovi.

🧊 Modelli 3D

Generazione 3D da testo o da una foto. L'output è in formato GLB (oltre a OBJ, FBX, STL, USDZ, USD, 3MF a seconda del modello), con un'immagine di anteprima: il job restituisce più file, ciascuno con la propria estensione.

La chiamata è la stessa degli altri contenuti multimediali: POST /media/generate e polling di 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":"tazza in ceramica, smalto opaco"}}'

id	input	≈ prezzo	caratteristiche
`3d/tripo-text`, `3d/tripo-image`	testo, foto	da $0.31	il più economico, mesh a quadrilateri, PBR
`3d/hunyuan-rapid-text`, `-image`	testo, foto	da $0.43	veloce, 5 formati di file
`3d/seed3d-image`	foto	da $0.50	GLB, OBJ, USD, USDZ
`3d/hunyuan-pro-text`, `-image`	testo, foto	da $0.71	fino a 1,5 milioni di poligoni
`3d/meshy-text`, `-image`, `-multi-image`	testo, foto, fino a 4 angolazioni	da $0.94	texture fino a 8K, posa del personaggio

Foto come texture. I modelli 3d/meshy-* accettano un'immagine separata (texture_photo) o una descrizione testuale del materiale (texture_text) — la texture si imposta indipendentemente dalla geometria. 3d/meshy-multi-image accetta fino a quattro angolazioni dello stesso oggetto, per ottenere una geometria più precisa.

Il prezzo è noto solo dopo la generazione

Il costo del 3D dipende dalle risorse effettivamente utilizzate, quindi l'importo esatto è noto solo dopo l'elaborazione del modello. Riserviamo l'importo massimo possibile e, al termine del calcolo, addebitiamo il costo effettivo e restituiamo la differenza. L'importo finale è sempre visibile nel campo cost_usd.

Nello studio questi modelli sono contrassegnati da un'etichetta e la generazione inizia solo dopo il tuo consenso.

Richiede tempo. La generazione 3D richiede da mezzo minuto a diversi minuti — più di un'immagine o di un breve video. Non è necessario tenere aperto il job: lo stato viene salvato e sono disponibili i webhook.

Costi e conservazione

L'addebito sul tuo saldo in USD corrisponde al costo effettivo della generazione — l'importo esatto è visibile in cost_usd al termine.
Le generazioni non riuscite non vengono addebitate — l'importo riservato viene restituito automaticamente.
I file vengono conservati sui nostri server per un periodo limitato (vedi retention_days in /media/models) — scaricali per conservarli.

Generazione di contenuti multimediali (video, immagini, musica) ​

Come funziona ​

1. Crea un’attività ​

2. Attendi il risultato ​

Webhook (invece del polling) ​

3. Elenco dei modelli e prezzi ​

Modelli ​

Parametri ​

🧊 Modelli 3D ​

Costi e conservazione ​

Generazione di contenuti multimediali (video, immagini, musica)

Come funziona

1. Crea un’attività

2. Attendi il risultato

Webhook (invece del polling)

3. Elenco dei modelli e prezzi

Modelli

Parametri

🧊 Modelli 3D

Costi e conservazione