미디어 생성(동영상, 이미지, 음악)

NordRouter는 텍스트 모델과 동일한 sk-nr-… 키와 잔액으로 이미지, 동영상, 음악을 생성할 수 있습니다. 토큰이나 패키지 없이 실제 생성 건별로 과금됩니다.

요청은 브라우저가 아닌 백엔드에서만 전송

브라우저에서 /media/*를 직접 호출할 수 없습니다. 요청이 CORS 검사를 통과하지 못해 Failed to fetch 오류로 중단됩니다.

이는 의도된 동작입니다. 이 엔드포인트는 Authorization 헤더에 키가 필요하며, 브라우저에 전달되는 모든 정보는 개발자 도구를 여는 누구에게나 보입니다. 키가 유출되면 다른 사람이 여러분의 잔액을 사용할 수 있습니다. fetch에 어떤 헤더를 추가해도 이를 막을 수 없습니다.

올바른 구조:

브라우저 → 서버(키는 여기에 보관) → nordrouter.com

완성된 파일은 일반 링크로 제공되므로 페이지의 <img src> 또는 <video src>에 바로 넣을 수 있습니다. 별도 설정은 필요하지 않습니다.

작동 방식

생성은 비동기로 처리됩니다(동영상과 음악은 수 초에서 몇 분 정도 소요됩니다).

작업 생성 — 모델과 매개변수를 지정해 POST /media/generate를 호출합니다.
결과 대기 — status가 done이 될 때까지 GET /media/job/:id를 폴링합니다.
파일 가져오기 — 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에 제공됩니다(링크 형식은 동일). 가격은 작업 전체 기준이며 두 트랙이 모두 포함되어 있습니다.

웹훅(폴링 대신 사용)

폴링을 원하지 않으면 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입니다. 값을 비교해 NordRouter에서 보낸 요청인지 확인하세요:

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-*`)	텍스트/사진→비디오, 모션, 아바타, 최대 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 — 성인 콘텐츠 필터(기본적으로 활성화).
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는 같은 물체의 각도별 이미지를 최대 4개까지 받으므로 지오메트리가 더 정확해집니다.

생성 후에만 가격 확인 가능

3D 생성 요금은 실제 사용된 리소스를 기준으로 계산되므로 정확한 금액은 모델 생성이 완료된 후에 확인할 수 있습니다. 가능한 최대 금액을 예약하고, 생성이 완료되면 실제 금액을 차감한 뒤 차액을 환불합니다. 최종 금액은 항상 cost_usd 필드에 표시됩니다.

스튜디오에서는 이러한 모델에 표시가 붙으며, 동의한 후에만 생성이 시작됩니다.

생성 시간이 깁니다. 3D 생성에는 30초에서 몇 분까지 걸리며, 이미지나 짧은 동영상보다 오래 걸립니다. 작업 화면을 열어 두지 않아도 됩니다. 상태가 저장되며 웹훅도 지원합니다.

비용 및 보관

USD 잔액에서 실제 생성 비용이 차감됩니다. 완료 후 cost_usd에서 정확한 금액을 확인할 수 있습니다.
생성에 실패하면 요금이 부과되지 않으며 예약 금액은 자동으로 환불됩니다.
파일은 제한된 기간 동안 서버에 저장됩니다(/media/models의 retention_days 참조). 보관하려면 다운로드하세요.

미디어 생성(동영상, 이미지, 음악) ​

작동 방식 ​

1. 작업 생성 ​

2. 결과 대기 ​

웹훅(폴링 대신 사용) ​

3. 모델 및 가격 목록 ​

모델 ​

매개변수 ​

🧊 3D 모델 ​

비용 및 보관 ​

미디어 생성(동영상, 이미지, 음악)

작동 방식

1. 작업 생성

2. 결과 대기

웹훅(폴링 대신 사용)

3. 모델 및 가격 목록

모델

매개변수

🧊 3D 모델

비용 및 보관