NodaroAccount
Nodaro 문서
문서노드 레퍼런스모델템플릿AI 에이전트(MCP)개발자셀프 호스팅리서치비교
REST API

Video Remake

Video Remake는 흔히 AI 모션 컨트롤이나 캐릭터 스왑이라고 부르는 기능입니다. 4~30초 동영상 속 인물, 반려동물, 제품, 장소를 움직임은 그대로 두고 내 이미지로 교체합니다.

Nodaro Cloud에서 사용할 수 있습니다

Video Remake API는 짧은 동영상 속 인물, 반려동물, 제품, 장소를 내 레퍼런스 이미지로 교체합니다. 동영상의 움직임, 구도, 타이밍, 소리는 그대로 유지됩니다. 클립의 오디오가 유지되고, 결과의 길이는 클립과 같습니다. 실행 견적을 무료로 받고, 실행을 시작한 뒤, 다른 작업처럼 그 작업을 추적하세요.

Video Remake는 흔히 AI 모션 컨트롤이나 캐릭터 스왑이라고 부르는 기능입니다. 정지 이미지 한 장의 캐릭터가 동영상의 동작을 따라 하게 하려면 모션 전이 노드를 쓰세요.

Video Remake는 Nodaro Cloud에서만 실행됩니다. 셀프 호스팅 설치에서는 모든 Video Remake 라우트가 404로 응답합니다. 라우트는 Bearer 토큰을 받습니다. 인증을 참조하세요.

엔드포인트

메서드경로하는 일비용
POST/v1/video-remake/estimate실행 견적을 받습니다. 아무것도 만들거나 예약하지 않습니다.무료
POST/v1/video-remake실행을 시작합니다. 202 { jobId }로 응답합니다. GET /v1/jobs/:id로 작업을 추적하세요.견적을 받은 실행 금액
POST/v1/video-remake/:jobId/full-quality/estimate초안 실행의 최고 품질 버전 견적을 받습니다. 아무것도 만들거나 예약하지 않습니다.무료
POST/v1/video-remake/:jobId/full-quality초안을 새 작업으로 1080p로 마무리합니다. 최고 품질을 참조하세요.견적을 받은 실행 금액
GET/v1/video-remake/style-choice엔진마다 실행의 style을 내가 고르는지 Nodaro가 모션으로 고정했는지, 엔진이 스타일 전용 실행을 받는지, 정밀 실행이 아트 스타일을 받는지 알려 줍니다. 공개 경로라 로그인이 필요하지 않습니다. 스타일을 참조하세요.무료
GET/v1/video-remake/advancedVideo Remake 페이지가 고급 옵션을 보여 주는지 알려 줍니다. 공개 경로라 로그인이 필요하지 않습니다. 스타일을 참조하세요.무료

요청 본문

두 라우트는 같은 본문을 받습니다.

필드하는 일
videoUrl필수입니다. 4~30초 길이의 원본 클립입니다.
roles필수입니다. 인물 역할 최대 6개, 장소 역할 1개, 반려동물 역할 3개, 제품 역할 3개입니다. 아래를 참조하세요.
references선택 사항입니다. 최대 5개의 고정 레퍼런스로, 어떤 역할로도 바뀌지 않으면서 동영상에 보여야 하는 것입니다. 고정 레퍼런스를 참조하세요.
prePrompt선택 사항입니다. 프롬프트의 맨 앞, 역할 지시보다 앞에 놓이는 내 문구입니다. 한도와 {role:N} 언급은 postPrompt와 같습니다.
postPrompt선택 사항입니다. 모델에 전달할 내 문구로, 최대 4,000자입니다. 역할은 {role:N}으로 언급하며, N은 빈 역할을 포함해 roles에서 1부터 셉니다.
preview선택 사항입니다. true이면 previewStart부터 클립의 4초를 렌더링합니다.
previewStart선택 사항입니다. 미리보기가 시작되는 지점(초)입니다. 기본값은 0입니다.
engine선택 사항입니다. 엔진으로, 기본값인 "nodaro-prism"(Nodaro Prism) 또는 "nodaro-pulse"(Nodaro Pulse)입니다. 엔진을 참조하세요.
style선택 사항입니다. 실행이 클립을 따르는 방식으로, 기본값인 "precise" 또는 "motion"입니다. 스타일을 참조하세요.
direction선택 사항이며, Nodaro Prism 전용입니다. 아트 스타일 { style: "<id>" }로, id는 스타일 피커 카탈로그의 id 중 하나입니다. 아트 스타일을 참조하세요.
motionLength선택 사항이며, Nodaro Pulse 전용입니다. 클립을 정수 초로 자르는 위치로, 기본값인 "cut-end" 또는 "cut-start"입니다.
resolution선택 사항입니다. 기본값인 "480p", "720p", "1080p" 중 하나입니다. Nodaro Pulse에서는 기본값인 "720p" 또는 "1080p"입니다.
draft선택 사항입니다. 기본값은 꺼짐이므로 480p 실행은 일반 실행입니다. true이면 480p 초안을 만들며, 그 같은 테이크를 나중에 최고 품질로 1080p로 마무리할 수 있습니다. 480p보다 높은 해상도에서 true는 거부됩니다. Nodaro Pulse에는 초안이 없습니다.
prepareReferences선택 사항입니다. 기본값은 true입니다. 레퍼런스 준비를 참조하세요.
quality지원 중단되었습니다. "draft"는 여전히 작동하며 480p 초안을 뜻합니다. 대신 resolution과 draft를 쓰세요.
sessionId, origin선택 사항입니다. 결과를 보관할 세션과 내 앱의 출처 레이블입니다.

역할은 동영상 속 누군가, 무언가 또는 배경을 지정하며, 한 대상이나 한 장소의 이미지를 0~3장 받습니다. 한 요청에 들어가는 이미지는 모두 합쳐 최대 30장입니다.

  • 인물: { kind: "person", name?, images, body?, outfit?, hair? }. name은 동영상 속 누구인지를 말합니다. 예: "the woman dancing".
  • 반려동물: { kind: "pet", name?, images, body?, coat? }.
  • 제품: { kind: "product", name?, images, shape?, finish? }.
  • 장소: { kind: "location", name?, images }. 기본 이름은 "the setting"입니다.

인물, 반려동물, 제품 역할은 name을 생략하거나 비워서 보낼 수 있습니다. 그러면 역할은 첫 번째 이미지로 이름이 정해지고, 동영상에서 그 이미지에 가장 잘 맞는 대상과 짝지어집니다. 이런 역할에는 이미지가 하나 이상 있어야 합니다. name은 최대 200자입니다. 트렌드 실행의 역할에는 항상 이름이 있습니다.

각 특성(body, outfit, hair, coat, shape, finish)은 내 이미지에서 가져오는 기본값 "new", 또는 동영상에서 유지하는 "original"입니다.

이미지가 없는(비어 있거나 null인) 역할은 그 대상이나 장소를 동영상 그대로 유지합니다. 이미지가 있는 역할, 레퍼런스, prePrompt 또는 postPrompt, 아트 스타일 중 하나 이상이 있어야 합니다. 아트 스타일은 스타일 전용 실행에서만 인정됩니다(아트 스타일 참조).

어떤 역할이든 미리보기에만 적용되는 설정 두 가지를 더 받을 수 있습니다. 전체 실행은 둘 다 무시합니다.

  • previewName은 미리보기에서 name 대신 쓰는 이름입니다.
  • inPreview: false는 그 역할을 미리보기에서 뺍니다. 그 역할의 이미지는 전송, 준비, 청구되지 않습니다. {role:N} 언급은 번호를 유지하며, 역할의 previewName으로, 없으면 name으로 읽힙니다.
{
  "videoUrl": "https://example.com/clip.mp4",
  "roles": [
    { "kind": "person", "name": "the woman dancing", "images": ["https://example.com/me.jpg"], "outfit": "original" }
  ],
  "preview": true
}

엔진

engine은 결과를 만드는 엔진을 고릅니다. 생략하면 Nodaro Prism을 그대로 씁니다.

엔진해상도초안최고 품질
"nodaro-prism", Nodaro Prism (기본값)480p(기본값), 720p, 1080p480p에서 draft: true일 때초안의 테이크 그대로 1080p로 다시 렌더링합니다
"nodaro-pulse", Nodaro Pulse720p(기본값), 1080p아니요없음: 1080p로 다시 실행하세요
  • Nodaro Pulse는 클립과 내 이미지를 바탕으로 새 테이크를 만듭니다.
  • Nodaro Pulse에서 draft: true는 draft_unsupported로, "480p"는 resolution_unsupported로 거부됩니다.
  • Nodaro Pulse는 정수 초 단위로 렌더링하므로 클립을 정수 초로 자릅니다. 자르는 위치는 motionLength가 정합니다. "cut-end"는 끝의 1초 미만 부분을, "cut-start"는 시작의 1초 미만 부분을 버립니다. Nodaro Prism은 motionLength를 무시합니다.
  • 미리보기는 두 엔진 모두 previewStart부터 4초입니다.
  • Nodaro Pulse는 실행당 모든 역할과 고정 레퍼런스를 합쳐 최대 10장의 이미지를 받습니다. 더 많으면 too_many_images로 거부됩니다. Nodaro Prism은 최대 30장을 받습니다.
  • 작업은 엔진을 input_data.engine에 기록하고, 완료된 작업의 출력은 engine에 엔진을 담습니다.

스타일

style은 실행이 클립을 따르는 방식을 정합니다. 생략하면 정밀을 그대로 씁니다.

  • 기본값인 "precise"는 클립을 정확히 따릅니다.
  • "motion"은 클립의 움직임을 따르고, 인물, 반려동물, 제품의 모습은 내 이미지에서 가져옵니다. 정밀보다 클립을 더 자유롭게 따릅니다.

두 스타일 모두 클립의 소리와 길이를 유지합니다. 모션은 정밀과 비용이 다를 수 있습니다. 정확한 가격을 보려면 같은 style을 POST /v1/video-remake/estimate에 보내세요.

작업은 보낸 style을 input_data.style에 기록합니다. style을 생략했다면 이 필드가 없으며, 이는 정밀이라는 뜻입니다. 트렌드 실행은 트렌드가 스타일을 정하므로 style을 무시합니다.

Nodaro는 엔진의 스타일을 모든 사용자에게 모션으로 고정할 수 있습니다. 그러면 그 엔진의 모든 실행과 견적은 style 값과 관계없이 모션 실행이 됩니다. GET /v1/video-remake/style-choice는 엔진마다 어느 쪽인지 알려 주며, 로그인이 필요하지 않습니다.

{ "engines": { "nodaro-prism": "user", "nodaro-pulse": "precise" } }

각 값은 "user"(위와 같이 내가 고름), "precise" 또는 "flex"(모션, 즉 style: "motion"이며, 위와 같이 고정됨)입니다. "precise"는 어떤 요청도 바꾸지 않습니다. Nodaro의 자체 앱은 그 엔진에서 정밀을 실행하고 스타일 선택을 숨깁니다. 그 엔진의 모든 실행과 견적은 "user"로 응답한 엔진에서처럼 보낸 style을 따릅니다. 내 앱에서는 "user"로 응답한 엔진에만 스타일 선택을 보여 주세요.

같은 응답에는 맵이 세 개 더 있으며, 각각 { "nodaro-prism": boolean, "nodaro-pulse": boolean }입니다.

  • styleOnly는 엔진이 스타일 전용 실행을 받는지 알려 줍니다. 아트 스타일을 참조하세요.
  • preciseArtStyle은 그 엔진에서 정밀 실행이 아트 스타일을 받는지 알려 줍니다.
  • preciseArtStyleAlone은 그 엔진에서 역할, 레퍼런스, 프롬프트 없이 아트 스타일만으로 정밀 실행의 변경이 되는지 알려 줍니다. 엔진이 이런 실행을 받기 전까지는 false로 응답합니다. Nodaro는 이런 요청을 모션 실행으로 실행할 수 있으며, 이 맵은 그것을 알려 주지 않습니다. 정밀 실행의 아트 스타일을 참조하세요.

세 맵 모두 엔진에만 따르므로 engines와 함께 읽으세요. Nodaro Pulse는 세 맵 모두 항상 false입니다. 이 필드가 생기기 전의 서버는 이를 생략합니다. 그러면 모든 엔진에 대해 false로 읽으세요. "flex"로 응답한 엔진에서는 모든 실행이 모션 실행입니다.

응답은 최대 1분 전의 것일 수 있습니다. 트렌드에는 영향이 없습니다.

Video Remake 페이지의 고급 옵션. Video Remake 페이지는 요청 본문의 두 필드 prepareReferences와 prePrompt를 고급 옵션 아래에서만 제공합니다. 이 옵션은 Nodaro가 켜지 않는 한 숨겨져 있으며, 페이지 전체와 모든 엔진에 하나의 설정이 적용됩니다. GET /v1/video-remake/advanced는 로그인이 필요하지 않고 { show: boolean }으로 응답하므로, 이 API로 만든 앱도 같은 옵션을 보여 주거나 숨길 수 있습니다. 응답은 페이지만 설명합니다. 모든 실행과 견적은 응답과 관계없이 prepareReferences와 prePrompt를 받습니다. 응답은 최대 1분 전의 것일 수 있습니다. SDK에는 아직 이를 위한 메서드가 없으므로 client.request()로 읽으세요.

Nodaro가 엔진에 맞춰 모션 실행을 준비하는 방식이 클립을 제한하는 동안에는, 27.9초를 넘는 클립의 모션 전체 실행이 clip_too_long_for_style로 거부됩니다. Nodaro Pulse에서는 클립을 정수 초로 자른 뒤의 길이로 셉니다. 미리보기에는 제한이 없습니다.

아트 스타일

direction: { style: "<id>" }는 동영상을 pop-art 같은 아트 스타일로 그립니다. id는 스타일 피커 카탈로그의 id 중 하나입니다. 아트 스타일은 Nodaro Prism만 받습니다. Nodaro Pulse는 400 art_style_needs_prism으로 거부합니다.

클립 전체를 다시 스타일링(스타일 전용). 모션 실행(style: "motion")은 바꿀 대상이 없어도, 즉 이미지가 있는 역할도 고정 레퍼런스도 없어도 아트 스타일을 받을 수 있습니다. 아트 스타일이 그 실행의 변경이므로 실행은 그대로 수락됩니다. prePrompt나 postPrompt도 그대로 추가됩니다. 실행은 클립 전체를 다시 스타일링하며, 인물, 장소, 움직임, 소리는 유지합니다.

  • 실행한 것만큼 청구됩니다. 기본 요금과 동영상이며, privacy 항목은 없습니다. referenceAudio 항목은 엔진에 대한 Nodaro의 설정이 그 단계를 실행할 때만, prompt 항목은 그 설정이 언어 모델에게 프롬프트를 쓰게 할 때만 나타납니다. 가격을 보려면 같은 본문을 POST /v1/video-remake/estimate에 보내세요.
  • 기본적으로 흑백 아트 스타일은 흑백으로 나옵니다. Nodaro는 대신 이를 다른 아트 스타일 실행처럼 실행할 수도 있으며, 그 경우 가격도 그와 같고 흑백으로 만들지 않습니다.
  • 미리보기는 전체 실행과 같은 경로를 따릅니다. 이미지가 있는 역할을 모두 뺀 미리보기(inPreview: false)는 전체 실행의 경로를 따르며, 아트 스타일이 미리보기의 변경으로 인정됩니다.
  • GET /v1/video-remake/style-choice가 그 엔진에 대해 styleOnly: true로 응답할 때만 제공하세요. Nodaro Prism이 false로 응답하는 동안에는, 바꿀 것이 달리 없는 아트 스타일이 400 validation_error로 거부됩니다. prePrompt나 postPrompt가 있으면 수락되지만, 다른 아트 스타일 실행과 같이 실행됩니다.
  • 실행은 여전히 모션이어야 합니다. "precise"로 응답한 엔진은 어떤 요청도 바꾸지 않으므로, 그 엔진의 모션 실행은 "user"로 응답한 엔진에서처럼 클립을 다시 스타일링합니다.

정밀 실행의 아트 스타일. GET /v1/video-remake/style-choice가 그 엔진에 대해 preciseArtStyle: true로 응답하면, 정밀 실행도 아트 스타일을 받습니다. Nodaro는 이 실행을 모션 실행과 같은 방식으로 만들 수 있으며, 모션 실행에서는 아트 스타일이 화면 전체에 훨씬 안정적으로 유지됩니다. 그 경우는 다음과 같습니다.

  • 작업은 여전히 보낸 스타일을 기록합니다. input_data.style이 없거나 "precise"입니다. 작업을 다시 읽거나 같은 본문을 다시 보내면 같은 실행을 요청하게 됩니다.
  • 같은 본문으로 보낸 견적, 가격, 최고 품질, 스타일 전용 동작이 모두 모션 실행의 것입니다.
  • 바꿀 것이 달리 없으면 스타일 전용 실행으로 수락됩니다.
  • style-choice는 어느 쪽이 적용되는지 보여 주지 않습니다. 실행 비용은 견적에서 읽으세요.
  • 스타일이 유지되기 전에 이 방식으로 만들어진 작업은 input_data.style: "motion"을 기록합니다.

그렇지 않으면 실행은 정밀로 만들어집니다. 클립은 정밀처럼 편집되고 인물도 정밀처럼 교체되며, 동영상 전체가 아트 스타일로 그려집니다. 이때는 다음과 같습니다.

  • 여기서는 아트 스타일만으로는 변경이 되지 않습니다. 이미지가 있는 역할, 고정 레퍼런스, prePrompt, postPrompt가 모두 없는 정밀 실행은 여전히 400 validation_error로 거부됩니다. 클립 전체만 다시 스타일링하려면 모션 실행(위의 스타일 전용)을 쓰세요.
  • 가격은 이런 실행에 대한 Nodaro의 설정이 역할 이미지를 먼저 아트 스타일로 다시 그릴 때만 바뀝니다. 같은 본문으로 보낸 견적에 나타납니다.
  • 작업은 아트 스타일을 input_data.direction에 기록합니다.
  • preciseArtStyle이 false이거나, 이 필드가 생기기 전의 서버가 이를 생략하면, 아트 스타일이 있는 정밀 실행은 400 art_style_needs_flex로 거부됩니다.

카탈로그에 없는 id는 400 unknown_art_style로, 저장된 무드보드는 400 art_style_not_supported로 거부됩니다. 400 art_style_needs_flex는 트렌드 실행의 아트 스타일, 그리고 Nodaro의 설정이 프롬프트를 정밀로 만드는 모션 실행의 아트 스타일에도 응답합니다. 그 설정은 고정된 스타일이 아니며, style-choice에 나타나지 않습니다.

고정 레퍼런스

references에는 어떤 역할로도 바뀌지 않으면서 동영상에 보여야 하는 것을 최대 5개 담습니다. 각각 { images, line }입니다.

  • images에는 한 대상의 이미지 1~3장을 담습니다.
  • line은 그 대상이 무엇인지 1~500자로 말합니다. 예: "the glass she drinks from".
  • 문구 속 {image}는 그 레퍼런스의 첫 번째 이미지를 뜻합니다. 예: "Use {image} for the sky". {image}가 없는 문구에는 끝에 덧붙여집니다.

레퍼런스는 받은 그대로 보내지며 준비 과정을 거치지 않습니다. 레퍼런스의 이미지도 30장 한도에 포함됩니다. 레퍼런스만으로도 실행할 수 있으며, 이미지가 있는 역할이 없어도 됩니다. 문구는 대상 자체를 설명하므로 {role:N}으로 역할을 언급할 수 없습니다.

레퍼런스 준비

prepareReferences가 false가 아니면, 인물, 반려동물, 제품 역할마다 그 이미지를 이미지 모델이 먼저 깔끔한 레퍼런스 사진 한 장으로 만듭니다. 그런 다음 그 사진들로 동영상을 만듭니다.

  • 준비에는 추가 크레딧이 들며, 견적에 breakdown.references로 표시됩니다. 이 크레딧은 준비가 실행될 때 청구되며, 이후 동영상이 실패해도 청구됩니다.
  • 약 1분이 더 걸립니다.
  • 어떤 역할의 사진을 만들 수 없으면, 그 역할은 내 이미지를 그대로 씁니다.
  • 장소는 준비하지 않습니다.

내 이미지를 그대로 쓰려면 prepareReferences: false를 보내세요.

클립 준비

원본 클립을 동영상 모델에 맞게 준비하는 방식은 Nodaro가 엔진마다 정합니다. 예를 들어 얼굴을 먼저 가릴지, 모델이 거부한 클립을 한 번 재시도할지를 정합니다. 실행에서는 이를 바꿀 수 없습니다. 이전 클라이언트가 보내는 faceMasking 필드는 받아들여지지만 무시됩니다.

완료된 작업의 출력에는 privacy: { applied, reason }이 담깁니다. applied는 동영상이 준비된 클립으로 만들어졌는지를 알려 주고, reason은 그 이유를 알려 줍니다.

견적

POST /v1/video-remake/estimate는 { engine, totalCredits, expectedCredits, breakdown, privacyCredits?, settlesLower }로 응답합니다. 견적에는 두 합계가 있습니다.

  • totalCredits는 실행이 시작될 때 예약되는 금액입니다.
  • expectedCredits는 실행에 청구될 것으로 예상되는 금액입니다. totalCredits를 넘지 않습니다. 실행에는 실제로 든 금액이 청구됩니다.
  • Nodaro Prism에서는 모델이 동영상 길이를 정하므로, 동영상은 가장 긴 출력만큼 예약합니다. 청구 예상액은 입력 클립 길이와 같은 길이의 출력 정도입니다. settlesLower: true가 이를 알려 줍니다. 최종 청구액은 totalCredits보다 낮은, 대략 expectedCredits 수준일 것으로 예상됩니다.
  • Nodaro Pulse에서는 두 합계가 같고 settlesLower는 false입니다. Nodaro Pulse는 요청한 길이 그대로 렌더링합니다.
  • engine은 견적의 대상 엔진입니다.

breakdown은 견적의 각 부분을 보여 주며, 표시용입니다.

부분내용
base실행 자체입니다.
references레퍼런스 준비입니다. 준비가 꺼져 있거나 준비할 것이 없으면 0입니다.
motion동영상이 예약하는 금액입니다. Nodaro Pulse에서는 동영상 비용입니다.
motionExpected동영상에 청구될 것으로 예상되는 금액으로, motion을 넘지 않습니다. Nodaro Prism 전용입니다.
privacy엔진 설정이 클립을 준비할 때의 클립 준비 비용입니다. 매번 실행되면 두 합계 모두에 포함되고, 아래의 재시도이면 어느 합계에도 포함되지 않습니다.
prompt엔진 설정이 프롬프트를 요청할 때, 언어 모델이 실행을 위해 쓰는 프롬프트의 비용입니다.
referenceAudio엔진 설정이 그 단계를 실행할 때, 동영상 모델을 위해 클립의 소리를 준비하는 비용입니다.

motion과 motionExpected는 둘 중 하나이므로, 내역의 합이 아니라 두 합계를 읽으세요.

엔진 설정이 거부된 클립을 재시도하는 경우, privacyCredits는 그 재시도가 실행될 때만 청구되는 추가 금액입니다. 어느 합계에도 포함되지 않습니다. 실행을 시작하려면 예약 금액과 privacyCredits를 모두 감당할 크레딧이 필요합니다.

반복 요청

실행을 재시도할 때는 8~200자의 같은 Idempotency-Key 헤더를 보내세요. 약 10초 안에 반복된 요청은 X-Dedup-Hit: 1 헤더와 함께 200 { jobId, deduped: true }로 응답합니다. 그 뒤에 반복된 요청은 첫 실행의 작업으로 202 { jobId }라고 응답합니다. 어느 경우든 새로 시작되거나 청구되는 것은 없습니다. 키가 없으면 요청마다 새 실행이 됩니다.

최고 품질

완료된 Nodaro Prism 초안은 최고 품질로 마무리할 수 있습니다. 초안은 draft: true로 480p에서 만든 Video Remake 또는 트렌드 실행입니다. 최고 품질은 같은 테이크를 1080p로 다시 렌더링하고, 클립에 맞추고, 클립의 원래 오디오를 입힙니다. 결과는 초안에 연결된 새 작업이며, 초안 자체는 그대로 남습니다.

최고 품질은 초안에만 있습니다. draft: true 없이 만든 480p 실행을 포함해, 일반 실행은 409 not_a_draft로 거부됩니다. 480p 테이크를 나중에 1080p로 마무리하려면 draft: true로 만드세요. Nodaro Pulse는 초안을 만들지 않으므로 최고 품질이 없습니다. 대신 1080p로 다시 실행하세요. 이 변경 전에 만든 Pulse의 최고 품질은 별도의 실행으로 계속 나열됩니다.

견적의 kind는 "same-take"입니다. 이전 서버는 kind를 생략하며, 뜻은 같습니다. 최고 품질은 초안이 완료된 후 7일 동안 사용할 수 있습니다.

메서드경로하는 일
POST/v1/video-remake/:jobId/full-quality/estimate견적을 받습니다. 무료이며, 아무것도 만들거나 예약하지 않습니다. { kind, totalCredits, breakdown, availableUntil }로 응답합니다.
POST/v1/video-remake/:jobId/full-quality시작합니다. 202 { jobId }로 응답합니다. 이 실행의 최고 품질이 이미 실행 중이거나 끝났으면 200 { jobId, existing: true }로 응답하며, 새로 시작되거나 청구되는 것은 없습니다. 선택 사항인 본문 { sessionId }를 받습니다.

:jobId는 초안의 작업 ID입니다. 견적에서 totalCredits는 최고 품질 작업 자체의 단계인 breakdown.base에, 초안 테이크의 1080p 렌더링인 breakdown.motionHd를 더한 값입니다. 이 초안의 이전 시도가 실패했지만 그 렌더링은 이미 끝낸 경우 motionHd는 0입니다. 렌더링을 다시 사용하고 마무리만 청구합니다. availableUntil은 7일이 끝나는 시점입니다. 가격은 초안에 따라 다르므로 먼저 견적을 받으세요.

초안 하나에는 최고 품질이 하나입니다. 작업이 초안을 키로 삼으므로, 반복되거나 동시에 들어온 요청은 같은 작업으로 응답하며 Idempotency-Key는 쓰이지 않습니다. 실패하거나 취소된 시도는 몇 번 다시 요청할 수 있습니다. 새 작업은 초안의 origin을 유지하며, sessionId는 그 작업을 내 세션 중 하나에 보관합니다.

모든 거부는 아무것도 청구되기 전에 일어납니다. 본문은 { error: { code, message } }입니다.

상태code발생 시점
401unauthorized인증된 사용자가 없습니다.
402insufficient_credits내 크레딧으로 비용을 감당할 수 없습니다. 시작 전용입니다. 워크스페이스에서는 거부한 한도에 따라 budget_exceeded, member_cap_exceeded, user_allowance_exceeded로 응답할 수도 있습니다.
404not_found내 작업이 아니거나 Video Remake 실행이 아닙니다. 시작에서는 내가 쓸 수 없는 sessionId도 해당합니다.
409not_completed실행이 끝나지 않았습니다.
409not_a_draft실행이 Nodaro Prism 초안이 아닙니다. draft: true 없이 만든 480p 실행을 포함한 일반 실행이거나, 초안을 만들지 않는 Nodaro Pulse 실행입니다. Pulse는 1080p로 다시 실행하세요.
409full_quality_pending최종 상태가 아니므로 나중에 다시 시도하세요. 본문에 retryable: true가 담깁니다. 이 초안에 대한 이전 시도의 1080p 렌더링이 검토 중이거나 아직 시작되지 않았습니다.
409full_quality_unavailable최종 상태입니다. 실행을 최고 품질로 마무리할 수 없습니다. 다시 렌더링할 것이 보관되지 않았거나, 완료 시각을 읽을 수 없거나, 1080p 마무리가 이 초안을 거부합니다. 시작에서는 모든 시도가 실패했거나 이 실행에 시작할 수 있는 시도가 없을 때도 해당합니다.
410draft_expired초안이 완료된 지 7일이 지났거나, 초안을 더 이상 최고 품질로 마무리할 수 없습니다.
422job_blocked배포 환경의 작업 정책이 요청을 막았습니다. 시작 전용입니다.
503job_read_failed지금은 초안을 읽을 수 없습니다. 본문에 retryable: true가 담깁니다. 다시 시도하세요.
503estimate_unavailable지금은 1080p 렌더링의 견적을 낼 수 없습니다. 잠시 후 다시 시도하세요.
503host_too_old이 플랫폼 버전에서는 최고 품질을 실행할 수 없습니다.

full_quality_pending과 full_quality_unavailable은 메시지가 아니라 코드로 구별하세요.

오류

모든 거부는 아무것도 청구되기 전에 일어납니다. 본문은 { error: { code, message } }입니다.

상태code발생 시점
400validation_error본문이 유효하지 않습니다. 이미지가 있는 역할, 레퍼런스, prePrompt나 postPrompt, 아트 스타일이 모두 없거나(아트 스타일은 styleOnly가 true일 때만 인정됩니다), 레퍼런스가 5개를 넘거나, 레퍼런스에 이미지가 없거나 3장을 넘거나, 한 종류의 역할이 허용된 수보다 많거나, 한 역할의 이미지가 3장을 넘거나, 이미지가 모두 합쳐 30장을 넘거나, 720p나 1080p에서 draft: true이거나, prePrompt나 postPrompt가 4,000자를 넘거나, origin이 유효하지 않거나, style이 "precise"나 "motion"이 아닌 경우입니다.
400draft_unsupported초안이 없는 engine: "nodaro-pulse"에 draft: true를 보냈습니다.
400resolution_unsupportedengine: "nodaro-pulse"에 resolution: "480p"를 보냈습니다.
400output_format_unsupportedengine: "nodaro-pulse"에 MOV 출력을 요청했습니다. MOV는 Nodaro Prism 실행만 반환할 수 있습니다.
400too_many_imagesNodaro Pulse 실행에서 모든 역할과 고정 레퍼런스를 합쳐 이미지가 10장을 넘습니다.
400raw_reference_token역할의 name이나 previewName, 레퍼런스의 line, prePrompt, postPrompt에 원시 레퍼런스 토큰 {image:, {video:, {audio:가 대소문자와 관계없이 들어 있습니다.
400invalid_role_mentionprePrompt나 postPrompt가 1부터 역할 수까지의 범위를 벗어난 N으로 {role:N}을 언급합니다. 레퍼런스의 line에 있는 모든 {role:N}도 해당합니다.
400no_roles_in_preview보낸 내용으로 판단했을 때 아무것도 바꾸지 않는 미리보기입니다. 미리보기에 남은 역할 중 이미지가 있는 역할, 고정 레퍼런스, prePrompt나 postPrompt, 아트 스타일이 모두 없습니다. 모든 역할을 뺀 미리보기도 레퍼런스나 프롬프트가 있거나, styleOnly가 true일 때 아트 스타일이 있으면 실행됩니다.
400prompt_too_long프롬프트가 너무 길어집니다. 이미지가 없는 역할의 {role:N}은 역할 이름으로 읽히므로, 4,000자 이내의 프롬프트도 합치면 엔진의 한도를 넘을 수 있습니다. Nodaro Pulse의 한도는 8,000자입니다.
400unsafe_urlvideoUrl, 역할 이미지, 레퍼런스 이미지가 공개 http 또는 https 주소가 아닙니다.
400video_unreadable클립의 길이를 읽을 수 없습니다. 재생할 수 있는 동영상이 아닙니다.
400clip_out_of_range클립이 4초보다 짧거나 30초보다 깁니다.
400clip_too_long_for_stylestyle: "motion" 전용이며, Nodaro가 엔진에 맞춰 모션 실행을 준비하는 방식이 클립을 제한하는 동안 적용됩니다. 클립이 27.9초를 넘는 전체 실행입니다. 메시지는 “This clip is too long for Motion. Use a shorter clip or choose Precise.”(이 클립은 모션에 쓰기에 너무 깁니다. 더 짧은 클립을 쓰거나 정밀을 선택하세요.)입니다.
400prompt_parts_not_allowed본문이 promptParts를 보냅니다. 이 필드는 트렌드의 프롬프트를 위해 Nodaro 플랫폼 자체만 보낼 수 있습니다.
400prompt_style_not_allowed본문이 promptStyle을 보냅니다. 이 필드는 Nodaro 플랫폼 자체만 보낼 수 있습니다. 실행의 문구는 그 실행의 style을 따릅니다.
400preview_out_of_range미리보기가 클립의 끝을 넘습니다. previewStart에 4를 더한 값이 클립 길이 이하여야 합니다.
400unnamed_role_needs_picturename도 이미지도 없는 인물, 반려동물, 제품 역할입니다. 이름 없는 역할은 첫 번째 이미지로 이름이 정해지므로 이미지가 하나 필요합니다.
400art_style_needs_prism아트 스타일을 받지 않는 engine: "nodaro-pulse"에 아트 스타일을 보냈습니다.
400art_style_needs_flexpreciseArtStyle이 true가 아닌데 정밀 실행에 아트 스타일을 보냈거나, 트렌드 실행, 또는 Nodaro의 설정이 프롬프트를 정밀로 만드는 모션 실행에 보냈습니다.
400unknown_art_styledirection.style이 스타일 피커 카탈로그의 id가 아닙니다.
400art_style_not_supporteddirection이 저장된 무드보드를 가리킵니다. Video Remake 실행은 이를 받을 수 없습니다.
400role_name_required이름 없는 역할이 있는 트렌드 실행입니다. 트렌드의 역할에는 항상 이름이 있습니다.
401unauthorized인증된 사용자가 없습니다.
402insufficient_credits내 크레딧으로 실행 비용을 감당할 수 없습니다. POST /v1/video-remake 전용입니다. 견적에 privacyCredits가 있으면 필요한 크레딧은 예약 금액에 privacyCredits를 더한 값입니다. 워크스페이스에서는 거부한 한도에 따라 budget_exceeded, member_cap_exceeded, user_allowance_exceeded로 응답할 수도 있습니다.
404not_foundsessionId가 내가 쓸 수 없는 세션을 가리킵니다. POST /v1/video-remake 전용입니다.
422job_blocked배포 환경의 작업 정책이 요청을 막았습니다. POST /v1/video-remake 전용입니다.
503host_too_old이 플랫폼 버전에서는 Video Remake를 실행할 수 없습니다.
503estimate_unavailable지금은 가격을 견적 낼 수 없습니다. 잠시 후 다시 시도하세요. /estimate 전용입니다.

SDK에서 사용

client.videoRemake는 모든 라우트를 감쌉니다. @nodaro/sdk/video-remake로도 가져올 수 있습니다.

run(params: VideoRemakeParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: VideoRemakeParams): Promise<VideoRemakeEstimate>
fullQualityEstimate(jobId: string): Promise<VideoRemakeFullQualityEstimate>
fullQuality(jobId: string, params?: { sessionId?: string }): Promise<VideoRemakeFullQualityResult>
styleChoice(): Promise<VideoRemakeStyleChoice> // GET /v1/video-remake/style-choice, public

VideoRemakeParams는 위의 요청 본문이며, engine은 VideoRemakeEngine, style은 VideoRemakeStyle("precise" | "motion"), motionLength는 VideoRemakeMotionLength 타입입니다. faceMasking은 이전 코드가 계속 작동하도록 타입에 남아 있지만, 지원 중단되었으며 서버는 이를 무시합니다. VideoRemakeEstimate는 견적입니다. run()은 idempotencyKey를 그대로 Idempotency-Key 헤더로 보냅니다. 없으면 헤더를 보내지 않습니다. styleChoice()는 VideoRemakeStyleChoice, 즉 { engines: { "nodaro-prism", "nodaro-pulse" }, styleOnly?, preciseArtStyle? }로 응답합니다. 각 엔진의 값은 VideoRemakeStyleChoiceOption인 "user", "precise" 또는 "flex"입니다. styleOnly와 preciseArtStyle은 엔진마다 불리언 값을 줍니다. 값이 없으면 false로 읽으세요. VideoRemakeParams는 direction?: { style: string }을 받으며, 견적의 breakdown에는 referenceAudio가 나올 수 있습니다.

const { engines, styleOnly } = await client.videoRemake.styleChoice()
if (styleOnly?.["nodaro-prism"] === true) {
  await client.videoRemake.run({ videoUrl, roles: [], style: "motion", direction: { style: "pop-art" } })
}
const params: VideoRemakeParams = {
  videoUrl,
  roles: [{ kind: "person", name: "the woman dancing", images: [myPhotoUrl], outfit: "original" }],
  preview: true,
  resolution: "480p",
}
const quote = await client.videoRemake.estimate(params)
const { jobId } = await client.videoRemake.run(params, { idempotencyKey: crypto.randomUUID() })

client.jobs.get(jobId)로 작업을 추적하세요. 미리보기 작업은 모든 입력을 input_data에 보관하므로, preview: false로 다시 실행해 같은 선택으로 클립 전체를 렌더링할 수 있습니다.

실행을 1080p로 마무리하려면 무료인 fullQualityEstimate(draftJobId)로 견적을 받은 다음 fullQuality(draftJobId)를 호출하세요. 견적의 kind는 VideoRemakeFullQualityKind이며, 값은 "same-take"입니다. 결과는 { jobId, existing? }입니다. existing: true는 이 실행의 최고 품질이 이미 실행 중이거나 끝났으며 아무것도 청구되지 않았다는 뜻입니다. 거부에는 VideoRemakeFullQualityRefusalCode가 담깁니다. full_quality_pending이면 err.details.retryable이 true이므로 나중에 다시 시도하세요.

const quote = await client.videoRemake.fullQualityEstimate(draftJobId) // free
const { jobId, existing } = await client.videoRemake.fullQuality(draftJobId)

CLI에서 사용

nodaro video-remake full-quality estimate <jobId> [--json]
nodaro video-remake full-quality run <jobId> [--session <id>] [--json]

estimate는 무료 견적입니다. 크레딧, 견적의 각 항목, 실행을 마무리할 수 있는 기한을 출력합니다. run은 크레딧을 쓰고 새 작업 ID를 출력합니다. 최고 품질이 이미 있으면 run은 그 작업을 출력하고 아무것도 청구하지 않습니다. full_quality_pending은 최종 상태가 아니므로 나중에 명령을 다시 실행하세요.

MCP에서 사용

MCP 도구는 video_remake입니다. 같은 필드를 스네이크 케이스로 받습니다. 예: pre_prompt, prepare_references, in_preview, engine, style, motion_length. 또한 Nodaro Prism의 아트 스타일인 art_style도 받습니다. 값은 스타일 피커 카탈로그의 id이며, 예를 들면 pop-art입니다. 모션 실행에서, 그리고 엔진이 받는 경우 정밀 실행에서 작동합니다. 역할 이미지와 레퍼런스가 없으면, 엔진이 스타일 전용 실행을 받는 경우 클립 전체를 다시 스타일링합니다. video_remake를 참조하세요. 클립 준비에 관한 설정은 받지 않습니다. confirm이 없으면 견적을 반환하고 아무것도 청구하지 않습니다. 사용자가 가격을 수락한 뒤 confirm: true로 호출하면 실행을 시작하고 작업 ID를 반환합니다. estimate_full_quality와 full_quality 도구는 초안이나 720p로 실행한 Nodaro Pulse의 최고 품질 버전 견적을 받고 시작합니다.

자주 묻는 질문

Video Remake는 무엇을 하나요?

Video Remake는 짧은 동영상 속 인물, 반려동물, 제품, 장소를 내 레퍼런스 이미지로 교체합니다. 동영상의 움직임, 구도, 타이밍, 소리는 그대로 유지되고, 결과의 길이는 클립과 같습니다.

Video Remake는 모션 컨트롤이나 캐릭터 스왑인가요?

네. Video Remake는 흔히 AI 모션 컨트롤이나 캐릭터 스왑이라고 부르는 기능입니다. 클립의 움직임, 구도, 타이밍, 소리는 그대로 유지되고, 그 속의 인물, 반려동물, 제품, 장소가 내 이미지로 바뀝니다. 정지 이미지 한 장의 캐릭터가 동영상의 동작을 따라 하게 하려면 모션 전이 노드를 쓰세요.

원본 동영상은 얼마나 길 수 있나요?

4~30초입니다. 더 짧거나 긴 클립은 아무것도 청구되기 전에 clip_out_of_range로 거부됩니다.

Video Remake 실행 비용은 어떻게 알 수 있나요?

실행할 때와 같은 본문으로 POST /v1/video-remake/estimate를 호출하세요. 무료이며, 실행이 시작될 때 예약되는 totalCredits와 실행에 청구될 것으로 예상되는 expectedCredits를 반환합니다. 내역의 합이 아니라 이 두 합계를 읽으세요.

클립 전체를 렌더링하기 전에 결과를 미리 볼 수 있나요?

네. preview를 true로 보내면 previewStart부터 클립의 4초를 렌더링합니다. 미리보기는 비용이 더 적고, 그 작업은 모든 입력을 보관하므로 preview를 false로 해서 다시 실행할 수 있습니다.

초안 실행을 최고 품질로 마무리할 수 있나요?

네, 초안이 완료된 후 7일 이내라면 가능합니다. Nodaro Prism에서 draft를 true로 해 480p로 실행을 만드세요. 그러면 POST /v1/video-remake/:jobId/full-quality가 같은 테이크를 1080p로 다시 렌더링해 새 작업으로 만듭니다. 먼저 견적 라우트로 무료 견적을 받으세요.

Video Remake는 어떤 엔진을 쓸 수 있나요?

두 가지입니다. Nodaro Prism이 기본값이며 480p, 720p, 1080p로 렌더링하고, draft를 true로 보내면 480p 초안을 만듭니다. Nodaro Pulse를 쓰려면 engine을 nodaro-pulse로 보내세요. Nodaro Pulse는 720p나 1080p로 렌더링하고, 초안이 없으며, 클립과 내 이미지를 바탕으로 새 테이크를 만듭니다.

내 클립의 얼굴을 가릴지 직접 고를 수 있나요?

아니요. 원본 클립을 준비하는 방식은 얼굴을 먼저 가릴지를 포함해 Nodaro가 엔진마다 정합니다. 이전 클라이언트가 보내는 faceMasking 필드는 받아들여지지만 무시됩니다.

Video Remake는 셀프 호스팅 설치에서도 작동하나요?

아니요. Video Remake는 Nodaro Cloud에서만 실행됩니다. 셀프 호스팅 설치에서는 모든 라우트가 404로 응답합니다.

최종 업데이트

목차