# 캐릭터

> AI 어시스턴트에서 캐릭터를 만들고, 포트레이트를 생성해 승인하고, 표정, 포즈, 앵글, 모션 클립을 추가해 레퍼런스로 다시 씁니다.

Source: https://nodaro.ai/ko/docs/mcp/tools/characters

**캐릭터 도구**를 사용하면 어시스턴트가 캐릭터 스튜디오 라이브러리의 캐릭터를 만들고 쓸 수 있습니다. 캐릭터는 모든 이미지와 동영상에서 같은 모습을 유지하도록 외모가 고정된 인물이나 형상입니다. 어시스턴트는 캐릭터를 만들고, 포트레이트를 생성해 승인하고, 표정, 포즈, 앵글, 조명 같은 변형을 추가합니다. 그다음 캐릭터를 모션 클립으로 움직이게 하고, 그 이미지를 다른 생성에 레퍼런스로 전달합니다. 앱에서 같은 작업을 하는 방법은 [캐릭터 스튜디오](https://nodaro.ai/docs/guides/character-studio)를 읽어 보세요.

## 캐릭터 수명 주기
### 캐릭터 만들기
`create_character`는 이름과 정체성인 설명, 성별, 스타일, 의상을 저장합니다. 아직 캐릭터에 포트레이트는 없습니다.

### 포트레이트 생성과 승인
`kind: "main"`으로 `generate_character`를 실행하면 포트레이트가 만들어집니다. 마음에 드는 포트레이트가 나올 때까지 실행한 다음, 그 작업을 `approve_portrait`에 전달하세요. 승인된 포트레이트가 캐릭터의 기준이 되고, 비전 모델이 기준 설명을 작성합니다.

### 변형 추가
`kind: "asset"`과 `attach_to_character_id`로 `generate_character`를 실행하면, 승인된 포트레이트로 표정, 포즈, 머리 앵글, 전신 앵글, 조명 변형을 만들고 각각 캐릭터에 저장합니다.

### 애니메이션과 재사용
`generate_character_motion`은 캐릭터를 모션 클립으로 만듭니다. `get_character`는 모든 이미지와 클립을 반환하며, 이를 [`generate_image`](https://nodaro.ai/docs/mcp/tools/image#generate_image)나 [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video)에 레퍼런스로 바로 전달할 수 있습니다.

## `list_characters`
내 캐릭터를 최근에 수정한 순서로 나열하며, 이름, 설명, 포트레이트, 종류별 변형 수, 정체성 텍스트를 함께 반환합니다. 보관한 캐릭터는 제외됩니다. `search`가 없으면 첫 페이지만 반환하므로, 사용자가 캐릭터 이름을 말하면 검색하세요.

**권한:** `assets:read`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `search` | string | 최대 5단어, 최대 200자입니다. 모든 단어가 대소문자와 관계없이 캐릭터의 이름이나 설명에 있어야 합니다. 빈 값은 검색하지 않음을 뜻합니다. |
| `limit` | integer | 1~100입니다. 기본값은 `50`입니다. |

**반환값:** 캐릭터 목록입니다. 이미지 URL은 `get_character`를 호출해 받으세요.

## `get_character`
캐릭터 하나의 전체 정보를 반환합니다. 모든 표정, 포즈, 모션, 머리 앵글, 전신 앵글, 조명 변형의 이름과 URL, 레퍼런스 사진, 그리고 변형에 있는 경우 실제 레퍼런스 URL입니다.

**권한:** `assets:read`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | **필수.** `list_characters`에서 받은 캐릭터 id입니다. |

**반환값:** `update_character`에 쓸 `updatedAt`을 포함한 캐릭터입니다. 캐릭터가 없거나 내 캐릭터가 아니면 오류를 반환합니다.

Nodaro Cloud에서는 캐릭터에 `training`도 들어 있습니다. 고충실도 학습의 상태로, `{ status, error, trainedAt, imageCount }` 형식입니다. `status`는 `untrained`, `queued`, `training`, `succeeded`, `failed`, `cancelled` 중 하나입니다. [`train_character`](#train_character) 실행을 확인하려면 이 값을 읽으세요.

## `create_character`
정체성을 담은 캐릭터를 만듭니다. 아직 포트레이트는 없으므로, 다음으로 `generate_character`로 생성하세요.

**권한:** `assets:write`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `name` | string | **필수.** `Kira` 같은 표시 이름으로, 최대 200자입니다. 활성 캐릭터 중에서 고유해야 하며, 중복되면 `name_taken`을 반환합니다. |
| `description` | string | 캐릭터가 누구인지로, 최대 2,000자입니다. |
| `gender` | string | 최대 50자입니다. |
| `style` | string | `realistic`, `anime`, `3d-pixar`, `illustration` 같은 시각 스타일입니다. |
| `base_outfit` | string | 기본 의상으로, 최대 1,000자입니다. |
| `seed_prompt` | string | 첫 포트레이트의 방향을 잡는 짧은 프롬프트로, 최대 4,000자입니다. |
| `identity_lock` | string | 생성되는 변형에서 캐릭터 스튜디오가 얼굴을 얼마나 엄격하게 유지할지입니다. `off`(기본값), `soft`, `strict` 중 하나입니다. |

**반환값:** 새 캐릭터의 id입니다.

## `update_character`
캐릭터의 정체성을 바꿉니다. 전달한 필드만 기록됩니다.

**권한:** `assets:write`. **크레딧:** 무료.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | **필수.** 캐릭터 id입니다. |
| `name`, `description`, `gender`, `style`, `base_outfit`, `seed_prompt`, `identity_lock` | | `create_character`와 같습니다. |
| `expected_updated_at` | string | `get_character`에서 받은 `updatedAt`입니다. 읽은 뒤에 캐릭터가 바뀌었으면 변경이 거부됩니다. |

**반환값:** 확인 메시지, 또는 `expected_updated_at`이 오래된 경우 충돌 오류입니다.

## `approve_portrait`
완료된 `generate_character` 결과를 캐릭터의 포트레이트로 만들고, 비전 모델이 이를 설명해 캐릭터의 기준 설명을 채웁니다.

**권한:** `assets:write`. **크레딧:** 설명을 위한 짧은 LLM 실행 1회입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `character_id` | string | **필수.** 캐릭터입니다. |
| `candidate_job_id` | string | **필수.** 내가 실행해 완료된 `generate_character` 작업입니다. |

**반환값:** 포트레이트 URL과 설명입니다. 설명 작성에 실패해도 포트레이트는 설정되며 설명은 비어 있습니다. 이때는 `recaption_character`를 실행하세요.

## `recaption_character`
비전 모델이 현재 포트레이트를 다시 설명하고, 새 기준 설명을 저장합니다. 포트레이트를 바꾼 뒤나 설명이 맞지 않을 때 사용하세요.

**권한:** `assets:write`. **크레딧:** 짧은 LLM 실행 1회입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | **필수.** 캐릭터입니다. |

**반환값:** 새 설명입니다. 캐릭터에 포트레이트가 없으면 `400 no_portrait`를 반환합니다.

## `generate_character`
캐릭터 포트레이트(`kind: "main"`) 또는 캐릭터의 변형(`kind: "asset"`)을 생성합니다.

**권한:** `workflows:execute`. **크레딧:** 이미지 모델의 가격입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `name` | string | **필수.** 캐릭터의 이름입니다. |
| `kind` | string | 포트레이트는 `main`(기본값), 변형은 `asset`입니다. |
| `description`, `gender`, `style`, `base_outfit` | string | 포트레이트용 정체성입니다. |
| `model` | string | 이미지 모델입니다. 기본값은 `gpt-image-2`입니다. |
| `asset_type` | string | `asset`에 필수입니다. `expressions`, `poses`, `lighting`, `headAngles`, `bodyAngles`, `custom` 중 하나입니다. `angles`는 `headAngles`의 이전 이름입니다. |
| `variant` | string | `asset`에 필수입니다. 변형으로, 표정은 `smile`이나 `angry`, 앵글은 `front`, `3/4 left`, `left profile`, `right profile`, `3/4 right`, `back`, 포즈는 `standing`이나 `walking`, 조명은 `daylight`, `night`, `dramatic` 같은 값입니다. |
| `attach_to_character_id` | string | 결과를 이 캐릭터에 저장하고, 캐릭터의 승인된 포트레이트를 소스로 씁니다. 승인된 포트레이트가 없으면 호출이 `portrait_required`를 반환합니다. |
| `attach_to_column` | string | `custom` 변형에서 `attach_to_character_id`와 함께 쓸 때 필수입니다. 저장할 위치로, `expressions`, `poses`, `angles`, `body_angles`, `lighting_variations`, `sheets`, `detail_closeups`, `outfit_variations`, `boards` 같은 값입니다. |
| `attach_name` | string | 저장할 변형의 이름입니다. 기본값은 변형 이름입니다. |
| `source_image_url` | string | 캐릭터에 연결하지 않을 때 쓰는 소스 이미지입니다. |

**반환값:** 작업 ID입니다. 포트레이트는 결과가 마음에 들면 그 작업을 `approve_portrait`에 전달하세요.

## `generate_character_motion`
캐릭터의 이미지 하나로 캐릭터를 짧은 모션 클립으로 만듭니다.

**권한:** `workflows:execute`. **크레딧:** 동영상 모델의 가격입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `motion_prompt` | string | **필수.** 무엇이 어떻게 움직이는지로, 최대 2,000자입니다. 예: “slow head turn left, eyes track the camera, soft smile”(천천히 왼쪽으로 고개를 돌리고, 눈은 카메라를 따라가며, 부드럽게 미소 짓기). |
| `name` | string | **필수.** 캐릭터의 이름입니다. |
| `attach_to_character_id` | string | 캐릭터에서 소스 이미지를 고르고, 클립을 캐릭터의 모션에 저장합니다. |
| `source_image_url` | string | 직접 고른 소스 이미지입니다. `attach_to_character_id`가 없으면 필수입니다. |
| `provider` | string | `kling`(기본값), `kling-turbo`, `kling-3.0`, `wan-i2v`, `wan-2.7-i2v` 중 하나입니다. |
| `attach_name` | string | 저장할 모션의 이름으로, 예를 들면 `walking`입니다. |
| `description`, `motion_description`, `gender`, `style`, `base_outfit` | string | 선택 사항인 정체성과 움직임 세부 정보입니다. |

`attach_to_character_id`를 쓰면 소스 이미지는 이 순서로 정해집니다. 내가 넣은 `source_image_url`, 캐릭터의 정면 전신 앵글, 다른 전신 앵글, 그다음 포트레이트입니다. 전신 이미지가 머리 포트레이트보다 훨씬 잘 움직이므로, 전신 앵글을 먼저 생성하세요.

**반환값:** 작업 ID입니다. 클립이 준비되면 카드에서 재생됩니다.

## `train_character`
저장된 캐릭터의 고충실도 모델을 그 캐릭터 자신의 이미지로 학습시킵니다. 그러면 프롬프트에서 그 캐릭터 하나를 @로 언급하는 **이미지 생성** 노드가 캐릭터의 정체성을 충실하게 유지합니다. 앱에서 같은 기능을 쓰는 방법은 [캐릭터 학습](https://nodaro.ai/docs/guides/character-training)을 읽어 보세요.

**권한:** `workflows:execute`와 `assets:write`. **크레딧:** 학습 1회당 1,650크레딧. **Nodaro Cloud 전용.**

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | **필수.** `list_characters`에서 받은 캐릭터 ID입니다. |
| `selected_image_urls` | array | 캐릭터의 이 이미지들로만 학습하며, 서로 다른 이미지가 4개 이상이어야 합니다. 기본값: 사용할 수 있는 모든 이미지. |

캐릭터에는 서로 다른 이미지가 4개 이상 있어야 합니다. 포트레이트, 레퍼런스 사진, 표정, 포즈, 앵글, 조명 변형이 모두 포함됩니다.

**반환값:** 즉시 `jobId`, `trainingId`, `triggerWord`와 함께 반환합니다. 학습은 약 15분 걸립니다. `get_character`의 `training` 필드로 진행 상황을 확인하세요.

- **거부.** 캐릭터의 학습이 진행 중이면 `already_training_or_not_found`를, 이미지가 4개보다 적으면 `insufficient_training_images`를 응답합니다.
- **크레딧.** 학습이 실패하거나 취소되면 크레딧이 환불됩니다. 이미 학습된 캐릭터를 다시 학습시키면 같은 비용이 다시 듭니다.
- **학습된 모델 제거.** 제거하면 유료 학습이 사라지고 되돌릴 수 없으므로, 이를 제거하는 MCP 도구는 없습니다. `DELETE /v1/characters/:id/lora`, SDK의 `client.characters.deleteLora(id)`, 또는 CLI의 `nodaro characters delete-lora <id>`를 사용하세요. [캐릭터 학습](https://nodaro.ai/docs/developers/api/character-training)을 참고하세요.

## 자주 묻는 질문

### 어시스턴트는 Nodaro에서 일관된 캐릭터를 어떻게 만드나요?

이름과 설명으로 create_character를 호출하고, generate_character로 포트레이트를 생성한 다음, 가장 좋은 것을 approve_portrait로 승인합니다. 승인된 포트레이트는 이후 캐릭터의 모든 변형과 모션 클립의 기준이 됩니다.

### 저장한 캐릭터를 이미지나 동영상에 쓰려면 어떻게 하나요?

list_characters로 캐릭터를 찾고, get_character로 이미지를 읽은 다음, 알맞은 포트레이트, 표정, 포즈 URL을 generate_image, image_to_image, generate_video의 reference_image_urls에 넣으세요.

### 변형 생성이 portrait_required로 실패하는 이유는 무엇인가요?

변형은 승인된 포트레이트를 소스로 씁니다. 먼저 kind를 main으로 해서 포트레이트를 생성하고, approve_portrait로 승인하세요.

### 모션 클립은 어떤 이미지에서 시작해야 하나요?

전신 이미지가 머리 포트레이트보다 훨씬 잘 움직입니다. 먼저 캐릭터의 전신 앵글을 생성하세요. 그러면 generate_character_motion이 정면 전신 앵글을 자동으로 사용합니다.

### 어시스턴트가 MCP로 캐릭터 모델을 학습시킬 수 있나요?

네, Nodaro Cloud에서 가능합니다. train_character는 서로 다른 이미지가 4개 이상 있는 저장된 캐릭터의 고충실도 모델을 학습시킵니다. 비용은 1,650크레딧이며, 학습이 실패하거나 취소되면 환불됩니다.