媒體生成（影片、圖片、音樂）

NordRouter 支援生成圖片、影片和音樂 — 使用與文字模型相同的 sk-nr-… 金鑰和帳戶餘額。依實際生成計費，不使用 token，也不需要購買套裝方案。

請求僅限從後端發送，不可從瀏覽器發送

不可直接從瀏覽器呼叫 /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-YOUR-KEY" \
  -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（連結格式相同）。價格以整個任務計算，已包含兩首曲目。

Webhook（取代輪詢）

若不想輪詢，可在 POST /media/generate 中傳入 callback_url 欄位，任務完成時，我們會透過 POST 請求主動傳送結果：

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": "您的密鑰"
  }'

當任務狀態變為 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，否則會重試。
使用 Webhook 後仍可輪詢 — 兩者可搭配使用，也可將 GET /media/job/:id 作為備援方式。

瞭解更多

任務生命週期、簽章驗證範例與傳送可靠性，請參閱**任務與 Webhook**。

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-*`)	文字/照片→影片、動作、虛擬人像、最高 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-*`)	文字→語音、人聲分離	每 1000 字元 $0.04 起

參數

參數依模型而異 — 確切清單請見 /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，3D 為 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。雙聲音對話：

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": "謝謝邀請我。" } ]
  } }

執行前，可使用相同的 model + input 呼叫 POST /media/estimate，取得該組設定的確切價格。

舊版參數名稱仍可使用

2026 年 10 月 19 日，參數名稱與值已統一（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 起	價格最低、四邊形網格、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 起	最多 150 萬個多邊形
`3d/meshy-text`, `-image`, `-multi-image`	文字、照片、最多 4 個視角	$0.94 起	最高 8K 紋理、角色姿勢

以照片作為紋理。 3d/meshy-* 模型接受獨立圖片（texture_photo）或以文字描述材質（texture_text）— 紋理可獨立於幾何形狀設定。3d/meshy-multi-image 可接受同一物件最多四個視角的照片，讓幾何形狀更精確。

生成後才能確定價格

3D 依實際消耗的資源計費，因此確切金額要在模型運算完成後才能確定。我們會預留最高可能費用，待運算完成後，扣除實際費用並退還差額。最終金額一律顯示於 cost_usd 欄位。

工作室會以標籤標示這類模型，且只有在您同意後才會開始生成。

需要較長時間。 3D 運算需要半分鐘到數分鐘，比圖片或短影片更久。不必持續開啟任務頁面：狀態會保留，並支援 Webhook。

費用與儲存

依實際生成費用從您的 USD 餘額扣款 — 完成後可在 cost_usd 查看確切金額。
生成失敗不收費 — 預留款項會自動退還。
檔案在我們的伺服器上僅儲存有限時間（請參閱 /media/models 中的 retention_days）— 請下載以便保存。

媒體生成（影片、圖片、音樂） ​

運作方式 ​

1. 建立任務 ​

2. 等待結果 ​

Webhook（取代輪詢） ​

3. 模型與價格清單 ​

模型 ​

參數 ​

🧊 3D 模型 ​

費用與儲存 ​

媒體生成（影片、圖片、音樂）

運作方式

1. 建立任務

2. 等待結果

Webhook（取代輪詢）

3. 模型與價格清單

模型

參數

🧊 3D 模型

費用與儲存