Nodaro 문서캐릭터
AI 어시스턴트에서 캐릭터를 만들고, 포트레이트를 생성해 승인하고, 표정, 포즈, 앵글, 모션 클립을 추가해 레퍼런스로 다시 씁니다.
캐릭터 도구를 사용하면 어시스턴트가 캐릭터 스튜디오 라이브러리의 캐릭터를 만들고 쓸 수 있습니다. 캐릭터는 모든 이미지와 동영상에서 같은 모습을 유지하도록 외모가 고정된 인물이나 형상입니다. 어시스턴트는 캐릭터를 만들고, 포트레이트를 생성해 승인하고, 표정, 포즈, 앵글, 조명 같은 변형을 추가합니다. 그다음 캐릭터를 모션 클립으로 움직이게 하고, 그 이미지를 다른 생성에 레퍼런스로 전달합니다. 앱에서 같은 작업을 하는 방법은 캐릭터 스튜디오를 읽어 보세요.
캐릭터 수명 주기
캐릭터 만들기
create_character는 이름과 정체성인 설명, 성별, 스타일, 의상을 저장합니다. 아직 캐릭터에 포트레이트는 없습니다.
포트레이트 생성과 승인
kind: "main"으로 generate_character를 실행하면 포트레이트가 만들어집니다. 마음에 드는 포트레이트가 나올 때까지 실행한 다음, 그 작업을 approve_portrait에 전달하세요. 승인된 포트레이트가 캐릭터의 기준이 되고, 비전 모델이 기준 설명을 작성합니다.
변형 추가
kind: "asset"과 attach_to_character_id로 generate_character를 실행하면, 승인된 포트레이트로 표정, 포즈, 머리 앵글, 전신 앵글, 조명 변형을 만들고 각각 캐릭터에 저장합니다.
애니메이션과 재사용
generate_character_motion은 캐릭터를 모션 클립으로 만듭니다. get_character는 모든 이미지와 클립을 반환하며, 이를 generate_image나 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 실행을 확인하려면 이 값을 읽으세요.
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
저장된 캐릭터의 고충실도 모델을 그 캐릭터 자신의 이미지로 학습시킵니다. 그러면 프롬프트에서 그 캐릭터 하나를 @로 언급하는 이미지 생성 노드가 캐릭터의 정체성을 충실하게 유지합니다. 앱에서 같은 기능을 쓰는 방법은 캐릭터 학습을 읽어 보세요.
권한: 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>를 사용하세요. 캐릭터 학습을 참고하세요.
자주 묻는 질문
어시스턴트는 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크레딧이며, 학습이 실패하거나 취소되면 환불됩니다.
관련 문서
캐릭터 스튜디오
캐릭터 학습
캐릭터 일관성
캐릭터 에셋
장소
최종 업데이트