캐릭터 학습

캐릭터 학습은 캐릭터의 이미지로 그 캐릭터 전용 모델을 만들어, 이미지 생성에서 원본과 가장 닮은 결과를 얻게 해 줍니다. 한 번의 호출로 학습을 시작하고, 끝날 때까지 폴링하고, 더 이상 필요하지 않으면 모델을 제거합니다. 학습이 끝나면 프롬프트가 그 캐릭터를 언급할 때마다 이미지 생성이 학습된 모델을 자동으로 사용합니다.

캐릭터 학습은 Nodaro Cloud에서만 실행되며, 셀프 호스팅 설치에는 해당 라우트가 없어 404로 응답합니다. 셀프 호스팅 설치에서는 캐릭터에 설명된 대로 승인된 포트레이트와 레퍼런스 이미지로 캐릭터의 일관성을 유지하세요. 이 라우트들은 Bearer 토큰을 받으며 내 캐릭터에만 작동합니다. 인증을 참조하세요.

SDK는 이 라우트들을 client.characters.train, trainingStatus, deleteLora로 감쌉니다. CLI에서는 nodaro characters train, training, delete-lora를 사용하세요. MCP로 연결된 AI 어시스턴트는 train_character로 학습을 시작하고 get_character로 진행을 확인합니다. 학습된 모델 제거는 MCP 도구로 제공되지 않습니다.

OAuth 앱 토큰으로 학습을 시작하거나 학습된 모델을 제거하려면, 캐릭터를 만들거나 삭제할 때와 같은 범위인 assets:write가 필요합니다. 이 범위가 없으면 아무것도 예약되기 전에 403 insufficient_scope로 응답합니다. 상태 읽기에는 범위가 필요 없습니다. 세션이나 개인 API 토큰에는 범위가 필요 없습니다.

엔드포인트

학습 전 준비

캐릭터에는 서로 다른 이미지가 4장 이상 있어야 합니다. 기본적으로 Nodaro는 다음 순서로 캐릭터에서 이미지를 모으고, 중복을 제거한 다음, 최대 20장으로 학습합니다.

1. 승인된 포트레이트.
2. 레퍼런스 사진.
3. 표정, 포즈, 머리 앵글, 전신 앵글.
4. 조명 변형.

일부 이미지만으로 학습하려면 본문에 { "selectedImageUrls": [...] }를 보내세요. 캐릭터 자신의 이미지 URL을 최대 200개까지 넣을 수 있습니다. 그러면 학습은 그 이미지만 사용하며, 최소 4장이 남아야 합니다. 목록을 생략하거나 비워 두면 해당하는 모든 이미지를 사용합니다.

캐릭터 시트는 시트 속 뷰들이 앵글을 반복하므로 포함되지 않습니다. 이미지가 4장보다 적으면 먼저 POST /v1/generate-character-asset으로 앵글과 표정을 몇 가지 생성하세요. 캐릭터를 참조하세요.

학습 시작

POST /v1/characters/:id/train은 1,650크레딧을 예약하고 학습을 시작합니다. 학습의 작업 ID, 학습 ID, 캐릭터의 트리거 단어와 함께 202로 응답합니다. 트리거 단어를 직접 입력할 필요는 없습니다. Nodaro가 프롬프트에 자동으로 추가합니다.

curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/train \
  -H "Authorization: Bearer $NODARO_API_KEY"

# Or train on a subset of the character's images
curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/train \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selectedImageUrls": ["https://cdn.nodaro.ai/characters/kira-portrait.png", "https://cdn.nodaro.ai/characters/kira-smile.png", "https://cdn.nodaro.ai/characters/kira-left.png", "https://cdn.nodaro.ai/characters/kira-right.png"]}'

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const training = await client.characters.train(characterId)
// Or a subset: client.characters.train(characterId, { selectedImageUrls: [...] })

{
  "jobId": "7a9c1e3b-5d2f-4b8a-9c6e-1f3d5b7a9c2e",
  "trainingId": "q4m8x2k6p1",
  "triggerWord": "TOK_kira_a1b2c3"
}

학습의 작업인 jobId는 학습과 함께 completed, failed, cancelled 중 하나로 끝나므로, GET /v1/jobs/:id/status로도 진행을 확인할 수 있습니다.

두 번 클릭해도 안전합니다. 학습이 대기 중이거나 실행 중일 때 다시 시작하면 409 already_training_or_not_found로 응답하며 아무것도 예약하지 않습니다. 토큰마다 분당 3회까지 학습을 시작할 수 있습니다.

학습 진행 확인

GET /v1/characters/:id/training은 학습 상태를 반환합니다. 학습에는 약 15분이 걸립니다. 10초 정도마다 폴링하세요. SDK에는 대기 도우미가 없습니다.

curl https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/training \
  -H "Authorization: Bearer $NODARO_API_KEY"

let training = await client.characters.trainingStatus(characterId)
while (training.status === 'queued' || training.status === 'training') {
  await new Promise((resolve) => setTimeout(resolve, 10_000))
  training = await client.characters.trainingStatus(characterId)
}
if (training.status !== 'succeeded') console.warn(training.status, training.error)

{
  "status": "succeeded",
  "trainingId": "q4m8x2k6p1",
  "error": null,
  "trainedAt": "2026-09-20T11:42:08Z",
  "version": "b81f4c0e9d27",
  "triggerWord": "TOK_kira_a1b2c3",
  "imageCount": 12
}

생성은 status가 succeeded인 동안에만 학습된 모델을 사용합니다. trainedAt과 version은 다시 학습하는 중이거나, 학습이 실패 또는 취소되었거나, 시작할 수 없었던 경우에도 값이 남아 있지만, 이런 상태에서는 모델이 사용되지 않습니다. 내 캐릭터가 아니거나 보관된 캐릭터는 404 not_found로 응답합니다.

학습된 모델로 이미지 생성

상태가 succeeded가 되면, @로 학습된 캐릭터를 정확히 하나만 언급하는 프롬프트를 쓰고 그 캐릭터를 노드에 연결한 상태로 이미지 생성을 실행하세요. 그러면 Nodaro는 선택한 모델과 레퍼런스 이미지 대신 학습된 모델을 사용합니다.

• 자동. 트리거 단어가 프롬프트 맨 앞에 자동으로 들어가고, @ 언급은 텍스트에서 제거됩니다.
• 이미지당 22크레딧. 학습된 모델의 가격이 선택한 모델의 가격을 대신합니다.
• 한 번에 학습된 캐릭터 하나. 프롬프트가 학습된 캐릭터를 둘 이상 언급하면, 이미지 생성은 레퍼런스 이미지와 함께 선택한 모델을 사용하는 방식으로 돌아갑니다.
• 이미지 생성 전용. 이미지 수정이나 동영상 노드 같은 다른 노드는 계속 캐릭터의 레퍼런스 이미지를 사용합니다.

이미지 생성 요청은 단일 노드 실행을, 편집기에서 쓰는 같은 기능은 캐릭터 학습을 참조하세요.

다시 학습 또는 모델 제거

• 다시 학습. 학습이 성공, 실패 또는 취소된 뒤에는 언제든 다시 학습을 시작할 수 있습니다. 매번 1,650크레딧이 들며, 새 모델이 이전 모델을 대체합니다.
• 제거. DELETE /v1/characters/:id/lora는 진행 중인 학습을 취소하고 크레딧을 환불하며, 학습된 모델을 삭제하고, 캐릭터의 학습 필드를 지웁니다. 그러면 상태는 untrained가 됩니다. { ok: true }를 반환하며, 되돌릴 수 없습니다. 이후 생성은 다시 레퍼런스 이미지를 사용합니다.
• 캐릭터 보관. 캐릭터를 보관해도 진행 중인 학습이 취소되고, 크레딧이 환불되며, 학습된 모델이 삭제됩니다.

curl -X DELETE https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/lora \
  -H "Authorization: Bearer $NODARO_API_KEY"

크레딧

잔액과 거래 내역은 크레딧을 참조하세요.

오류

이 라우트들이 직접 쓰는 거부 응답은 이전 본문 형식을 사용합니다. 코드는 그냥 문자열인 { "error": "<code>" }이며, 최상위 message가 함께 올 때도 있습니다. 범위, 크레딧, 요청 한도, 작업 정책 거부는 일반적인 { "error": { "code", "message" } } 형식을 사용합니다. SDK는 두 형식을 모두 NodaroError.code와 .message로 읽습니다.