# Video Remake

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

Source: https://nodaro.ai/ko/docs/developers/api/video-remake

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

Video Remake는 흔히 AI 모션 컨트롤이나 캐릭터 스왑이라고 부르는 기능입니다. 정지 이미지 한 장의 캐릭터가 동영상의 동작을 따라 하게 하려면 [모션 전이](https://nodaro.ai/docs/nodes/video/motion-transfer) 노드를 쓰세요.

Video Remake는 Nodaro Cloud에서만 실행됩니다. 셀프 호스팅 설치에서는 모든 Video Remake 라우트가 `404`로 응답합니다. 라우트는 Bearer 토큰을 받습니다. [인증](https://nodaro.ai/docs/developers/api/authentication)을 참조하세요.

## 엔드포인트
| 메서드 | 경로 | 하는 일 | 비용 |
| --- | --- | --- | --- |
| `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로 마무리합니다. [최고 품질](#full-quality)을 참조하세요. | 견적을 받은 실행 금액 |
| `GET` | `/v1/video-remake/style-choice` | 엔진마다 실행의 `style`을 내가 고르는지 Nodaro가 모션으로 고정했는지, 엔진이 스타일 전용 실행을 받는지, 정밀 실행이 아트 스타일을 받는지 알려 줍니다. 공개 경로라 로그인이 필요하지 않습니다. [스타일](#style)을 참조하세요. | 무료 |
| `GET` | `/v1/video-remake/advanced` | Video Remake 페이지가 고급 옵션을 보여 주는지 알려 줍니다. 공개 경로라 로그인이 필요하지 않습니다. [스타일](#style)을 참조하세요. | 무료 |

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

| 필드 | 하는 일 |
| --- | --- |
| `videoUrl` | 필수입니다. 4~30초 길이의 원본 클립입니다. |
| `roles` | 필수입니다. 인물 역할 최대 6개, 장소 역할 1개, 반려동물 역할 3개, 제품 역할 3개입니다. 아래를 참조하세요. |
| `references` | 선택 사항입니다. 최대 5개의 고정 레퍼런스로, 어떤 역할로도 바뀌지 않으면서 동영상에 보여야 하는 것입니다. [고정 레퍼런스](#fixed-references)를 참조하세요. |
| `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)입니다. [엔진](#engines)을 참조하세요. |
| `style` | 선택 사항입니다. 실행이 클립을 따르는 방식으로, 기본값인 `"precise"` 또는 `"motion"`입니다. [스타일](#style)을 참조하세요. |
| `direction` | 선택 사항이며, Nodaro Prism 전용입니다. 아트 스타일 `{ style: "<id>" }`로, id는 [스타일](https://nodaro.ai/docs/nodes/creative-controls/style) 피커 카탈로그의 id 중 하나입니다. [아트 스타일](#art-styles)을 참조하세요. |
| `motionLength` | 선택 사항이며, Nodaro Pulse 전용입니다. 클립을 정수 초로 자르는 위치로, 기본값인 `"cut-end"` 또는 `"cut-start"`입니다. |
| `resolution` | 선택 사항입니다. 기본값인 `"480p"`, `"720p"`, `"1080p"` 중 하나입니다. Nodaro Pulse에서는 기본값인 `"720p"` 또는 `"1080p"`입니다. |
| `draft` | 선택 사항입니다. 기본값은 꺼짐이므로 480p 실행은 일반 실행입니다. `true`이면 480p 초안을 만들며, 그 같은 테이크를 나중에 [최고 품질](#full-quality)로 1080p로 마무리할 수 있습니다. 480p보다 높은 해상도에서 `true`는 거부됩니다. Nodaro Pulse에는 초안이 없습니다. |
| `prepareReferences` | 선택 사항입니다. 기본값은 `true`입니다. [레퍼런스 준비](#reference-preparation)를 참조하세요. |
| `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`, 아트 스타일 중 하나 이상이 있어야 합니다. 아트 스타일은 스타일 전용 실행에서만 인정됩니다([아트 스타일](#art-styles) 참조).

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

- `previewName`은 미리보기에서 `name` 대신 쓰는 이름입니다.
- `inPreview: false`는 그 역할을 미리보기에서 뺍니다. 그 역할의 이미지는 전송, 준비, 청구되지 않습니다. `{role:N}` 언급은 번호를 유지하며, 역할의 `previewName`으로, 없으면 `name`으로 읽힙니다.

```json
{
"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, 1080p | 480p에서 `draft: true`일 때 | 초안의 테이크 그대로 1080p로 다시 렌더링합니다 |
| `"nodaro-pulse"`, Nodaro Pulse | 720p(기본값), 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`는 엔진마다 어느 쪽인지 알려 주며, 로그인이 필요하지 않습니다.

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

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

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

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

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

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

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

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

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

```ts
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`가 나올 수 있습니다.

```ts
const { engines, styleOnly } = await client.videoRemake.styleChoice()
if (styleOnly?.["nodaro-prism"] === true) {
await client.videoRemake.run({ videoUrl, roles: [], style: "motion", direction: { style: "pop-art" } })
}
```

```ts
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`이므로 나중에 다시 시도하세요.

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

## CLI에서 사용
```bash
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`](https://nodaro.ai/docs/mcp/tools/video#video_remake)입니다. 같은 필드를 스네이크 케이스로 받습니다. 예: `pre_prompt`, `prepare_references`, `in_preview`, `engine`, `style`, `motion_length`. 또한 Nodaro Prism의 아트 스타일인 `art_style`도 받습니다. 값은 [스타일](https://nodaro.ai/docs/nodes/creative-controls/style) 피커 카탈로그의 id이며, 예를 들면 `pop-art`입니다. 모션 실행에서, 그리고 엔진이 받는 경우 정밀 실행에서 작동합니다. 역할 이미지와 레퍼런스가 없으면, 엔진이 스타일 전용 실행을 받는 경우 클립 전체를 다시 스타일링합니다. [`video_remake`](https://nodaro.ai/docs/mcp/tools/video#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로 응답합니다.
