크리처

크리처 API는 반려동물, 드래곤, 마스코트처럼 모습이 고정된 동물과 인간이 아닌 존재를 관리합니다. 크리처에는 승인된 대표 이미지, 작성된 설명, 변형 이미지가 있으며, 이미지 노드와 동영상 노드가 이를 재사용하므로 크리처가 모든 샷에서 같은 모습으로 나옵니다. 크리처는 오브젝트처럼 작동하며, 자유 텍스트 species, 이름이 붙은 보드, 선택 사항인 보이스 세 가지가 추가됩니다.

이 라우트는 모든 에디션에서 작동하며 Bearer 토큰을 사용합니다. 개인 API 토큰(ndr_…), OAuth 앱 토큰(ndr_app_…), 또는 Community Edition에서는 세션 토큰을 보내세요. 인증을 참조하세요. CLI에는 크리처 명령이 없으므로 REST, SDK, MCP를 사용하세요.

엔드포인트

크리처에 담기는 정보

크리처 목록과 읽기

GET /v1/creatures는 내 활성 크리처를 반환합니다. 오브젝트 목록과 같은 매개변수인 archived=true, projectId, q, 그리고 선택 사항인 limit(최대 500)과 cursor를 받습니다. q는 이름이나 설명에 그 단어가 모두 들어 있는 크리처만 남기며, 대소문자는 구분하지 않습니다. 캐릭터와 같은 검색입니다. limit이 없으면 전체 목록을 받습니다. limit이 있으면 한 페이지와 nextCursor를 받으며, nextCursor가 null이 될 때까지 다시 보내세요.

GET /v1/creatures/:id는 크리처 하나를 반환합니다. 보관된 크리처는 404 not_found를 반환합니다.

curl "https://app.nodaro.ai/v1/creatures?limit=50" \
  -H "Authorization: Bearer $NODARO_API_KEY"

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

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

const { creatures, nextCursor } = await client.creatures.list({ limit: 50 })
const { creatures: archived } = await client.creatures.listArchived()

크리처 만들기 또는 수정

POST /v1/creatures는 본문에 id가 없으면 크리처를 만들고, 있으면 수정합니다. 만들 때는 nodeId와 name이 필요합니다. 캔버스 노드가 없으면 nodeId에 "scripted" 같은 아무 라벨이나 사용하세요. 만들면 { id }를, 수정하면 { id, updatedAt }을 반환합니다.

수정할 때는 보낸 필드만 기록됩니다. 에셋 버킷은 수정으로 기록되지 않지만, boards는 직접 설정할 수 있습니다. 교체하려면 전체 목록을 보내세요. expectedUpdatedAt을 보내면, 내가 읽은 뒤 누군가 크리처를 변경한 경우 수정이 409 concurrent_modification으로 거부됩니다.

curl -X POST https://app.nodaro.ai/v1/creatures \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Ember",
    "species": "red dragon",
    "description": "Young dragon with copper scales and a chipped left horn",
    "style": "realistic"
  }'

const { id } = await client.creatures.create({
  nodeId: 'scripted',
  name: 'Ember',
  species: 'red dragon',
  description: 'Young dragon with copper scales and a chipped left horn',
  style: 'realistic',
})

await client.creatures.update(id, {
  voice: { voiceId: 'Callum', voiceName: 'Callum', traits: 'gravelly, slow', voiceType: 'premade' },
})

보드

보드는 한 가지 모습이나 분위기에 대한 크리처의 촘촘한 레퍼런스 시트입니다. 이미지 생성의 generate-image/creature-board 프리셋으로 보드를 만든 다음, 그 URL을 boards에 저장하세요. 프리셋과 레퍼런스 보드를 참조하세요.

대표 이미지와 변형 생성

POST /v1/generate-creature는 후보마다 작업을 하나씩 시작하고 jobIds를 반환합니다. 후보가 하나인 요청은 jobId도 반환합니다. attachToCreatureId를 보내고 count가 1이면, 작업이 완료될 때 결과가 대표 이미지가 됩니다. 후보가 여러 개이면 아무것도 연결되지 않으므로, 마음에 드는 후보를 승인하세요.

POST /v1/generate-creature-asset은 변형 하나를 생성하고 { jobId }를 반환합니다. assetType은 angles, poses, variations, custom 중 하나입니다. 결과를 버킷에 추가하려면 attachToCreatureId, attachToColumn(angles, poses, variations 중 하나), attachName을 보내세요. custom 변형은 열을 지정해야 합니다.

curl -X POST https://app.nodaro.ai/v1/generate-creature \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "species": "red dragon",
    "count": 1,
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a"
  }'

curl -X POST https://app.nodaro.ai/v1/generate-creature-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "assetType": "poses",
    "variant": "wings spread",
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
    "attachToColumn": "poses",
    "attachName": "wings spread"
  }'

const { jobIds } = await client.creatures.generate({
  name: 'Ember',
  species: 'red dragon',
  count: 4,
})

await client.creatures.generateAsset({
  name: 'Ember',
  assetType: 'poses',
  variant: 'wings spread',
  attachToCreatureId: id,
  attachToColumn: 'poses',
  attachName: 'wings spread',
})

대표 이미지 애니메이션 만들기

POST /v1/generate-creature-motion은 크리처 이미지를 대기 루프, 어슬렁거리는 걸음, 공격 같은 클립으로 바꾸고 { jobId }를 반환합니다. sourceImageUrl은 필수입니다. attachToCreatureId와 attachName을 보내면 클립이 motionClips에 추가됩니다.

curl -X POST https://app.nodaro.ai/v1/generate-creature-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "motionPrompt": "slow idle breathing, tail sways, smoke curls from the nostrils",
    "sourceImageUrl": "https://cdn.nodaro.ai/creatures/ember-main.png",
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
    "attachName": "idle"
  }'

await client.creatures.generateMotion({
  name: 'Ember',
  motionPrompt: 'slow idle breathing, tail sways, smoke curls from the nostrils',
  sourceImageUrl: ember.sourceImageUrl!,
  provider: 'kling-turbo',
  duration: 5,
  attachToCreatureId: id,
  attachName: 'idle',
})

seedance(Seedance 1.5 Pro)는 이전 모델입니다. 라우트는 여전히 이 값을 받지만, 모델 카탈로그(GET /v1/models)에 더 이상 나오지 않으므로 표에 행이 없습니다.

대표 이미지 승인

POST /v1/creatures/:id/approve-main-image에 { candidateJobId, expectedUpdatedAt? }을 보내면, 완료된 후보가 대표 이미지로 설정되고 같은 호출에서 canonicalDescription이 작성됩니다. 응답은 { sourceImageUrl, canonicalDescription }입니다. 설명을 작성하지 못해도 대표 이미지는 설정되며 설명은 비어 있습니다. 이때 SDK는 null을 반환합니다.

POST /v1/creatures/:id/llm-caption은 설명을 다시 작성하고 { canonicalDescription }을 반환합니다. 설명을 작성할 수 없으면 502를, 아직 대표 이미지가 없으면 400 main_image_required를 반환합니다. 두 라우트 모두 반복해서 호출해도 안전합니다. 승인은 무료입니다. llm-caption은 호출 1회에 8크레딧이 들며, 실패한 호출(502)은 환불됩니다.

curl -X POST https://app.nodaro.ai/v1/creatures/0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "1c9e7a5b-3d2f-4c8e-9a4b-8f6d2e1a4c3b" }'

const ember = await client.creatures.get(id)
const approved = await client.creatures.approveMainImage(id, jobIds[0], ember.updatedAt)
if (approved.canonicalDescription === null) await client.creatures.recaption(id)

크리처 보관, 복원, 삭제

보관은 { success: true, archived: true }를 반환하며, 반복해도 달라지는 것은 없습니다. 복원은 { id, name }을 반환하며, 같은 이름의 활성 크리처가 있으면 (restored) 접미사가 붙습니다. 영구 삭제는 보관된 크리처에만 작동하며(그렇지 않으면 400 not_archived), 크리처와 크리처가 참조하는 파일 중 내 파일을 모두 제거합니다. 다른 사용자의 생성 작업이 만든 파일이나, 다른 사용자의 업로드 폴더 또는 라이브러리에 있는 파일은 저장소에 남으며, 내 저장 용량에 포함된 적이 없습니다.

크리처가 말하게 하기

크리처 전용 라우트는 필요하지 않습니다. 크리처의 보이스로 음성을 만든 다음, 대표 이미지에 립싱크하세요.

const speech = await client.nodes.runAndWait('text-to-speech', {
  text: 'I knocked the vase off the shelf. I regret nothing.',
  voice: ember.voice!.voiceId,
  provider: ember.voice!.ttsProvider,
  voiceType: ember.voice!.voiceType,
})

const clip = await client.nodes.runAndWait('lip-sync', {
  imageUrl: ember.sourceImageUrl!,
  audioUrl: speech.audioUrl,
  provider: 'kling-avatar',
})

nodes.runAndWait와 원시 POST /v1/<node-type> 라우트는 단일 노드 실행을 참조하세요.

크리처를 샷에 넣기

이미지 생성에서 크리처를 source: "wired-creature"인 구조화된 레퍼런스로 전달하세요. 크리처는 해부 구조, 무늬, 색을 유지하는 문구와 함께 자동으로 첨부됩니다. 프롬프트에서 크리처 이름을 부를 수도 있습니다. @ember:1을 입력하면 입력한 위치에 크리처가 배치됩니다. 역할로 이미지에서 무엇을 가져올지 고를 수 있습니다. 예: @ember:1:markings. 역할은 creature, anatomy, markings, pose, color, style입니다.

{
  "prompt": "a wide shot of @ember:1 landing on the castle wall",
  "connectedReferences": [
    { "id": "cr-1", "defaultName": "Ember", "source": "wired-creature", "url": "https://cdn.nodaro.ai/creatures/ember-main.png" }
  ]
}

워크플로에서는 대신 동물/크리처 에셋 노드를 이미지 노드나 동영상 노드에 연결하세요.

MCP에서 사용

MCP 도구 레퍼런스를 참조하세요.

크레딧

Nodaro Cloud에서 대표 이미지 요청은 이미지 모델 가격에 count를 곱한 값이며, 첫 작업이 시작되기 전에 예약됩니다. 변형은 이미지 모델 가격이고, 모션 클립은 동영상 모델로 이미지에서 동영상을 만드는 가격입니다. 승인과 승인 시 작성되는 설명은 무료입니다. llm-caption은 호출 1회에 8크레딧이 들며, 실패한 호출은 환불됩니다.

오류