오브젝트

오브젝트 API는 오브젝트/소품 스튜디오가 소품과 제품에 대해 하는 모든 작업을 스크립트로 실행합니다. 오브젝트를 만들고, 대표 이미지 후보를 생성하고, 그중 하나를 승인한 다음, 앵글, 재질, 변형 베리언트와 모션 클립을 추가합니다. 그러면 이미지 노드와 동영상 노드가 오브젝트를 재사용하므로, 같은 랜턴, 자동차, 의자가 모든 샷에서 똑같이 보입니다.

이 라우트는 모든 에디션에서 작동하며 Bearer 토큰을 받습니다. 개인 API 토큰(ndr_…), OAuth 앱 토큰(ndr_app_…), 또는 Community Edition에서는 세션 토큰을 사용합니다. 모든 라우트는 호출자 범위로 제한됩니다. 인증을 참조하세요.

엔드포인트

오브젝트의 구성

에셋 버킷

레퍼런스 사진

무드 보드는 오브젝트와 함께 전달됩니다. 오브젝트를 사용하는 모든 노드는 이미지를 연결하지 않아도 이 사진들을 추가 레퍼런스로 받으며, 각 사진의 kind는 그 사진이 무엇을 위한 것인지 모델에게 알려 줍니다.

사진은 최대 20장까지 추가할 수 있으며, 종류별 개수에는 제한이 없습니다. 주인공 소품이나 대표 제품이라면 첫 생성 전에 사진을 3~6장 추가하세요. 그러면 첫 결과가 훨씬 더 충실해집니다.

오브젝트 목록

GET /v1/objects는 활성 오브젝트를 최신순으로 반환합니다. 보관함을 보려면 archived=true를, 프로젝트 하나로 좁히려면 projectId를 추가하세요. 이름이나 설명에 그 단어가 모두 들어 있는 오브젝트만 남기려면 q를 추가하세요. 대소문자는 구분하지 않으며, 캐릭터와 같은 검색입니다. MCP list_objects 도구는 같은 검색을 search로 받습니다. limit이 없으면 라우트는 전체 목록을 반환합니다. limit(최대 500)을 지정하면 한 페이지와 nextCursor를 반환합니다. 이 값이 null이 될 때까지 cursor로 다시 전달하세요.

curl "https://app.nodaro.ai/v1/objects?limit=100" \
  -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 page = await client.objects.list({ limit: 100 })
const next = await client.objects.list({ limit: 100, cursor: page.nextCursor! })
const { objects: archived } = await client.objects.listArchived()

nodaro objects list --json
nodaro objects list --archived

GET /v1/objects/:id는 pendingJobs와 함께 오브젝트 하나를 반환합니다. 보관된 오브젝트는 존재하지 않는 오브젝트와 똑같이 404 not_found를 반환합니다.

오브젝트 만들기 또는 업데이트

POST /v1/objects는 본문에 id가 없으면 오브젝트를 만들고, 있으면 업데이트합니다. 만들 때는 nodeId와 name이 필요합니다. 캔버스 노드가 없으면 nodeId에 "scripted" 같은 아무 레이블이나 사용하세요.

업데이트에서는 보낸 필드만 기록됩니다. 에셋 버킷은 업데이트로 기록되지 않으므로, 저장이 작업에서 추가 중인 베리언트를 덮어쓸 수 없습니다. expectedUpdatedAt에 오브젝트의 현재 updatedAt 값을 넣어 보내면, 읽은 뒤에 누군가 오브젝트를 변경한 경우 업데이트가 거부됩니다. 이때 라우트는 409 concurrent_modification으로 응답합니다.

curl -X POST https://app.nodaro.ai/v1/objects \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Antique Lantern",
    "description": "Weathered brass lantern with hand-engraved filigree",
    "category": "tool",
    "style": "realistic"
  }'

const { id } = await client.objects.create({
  nodeId: 'scripted',
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  category: 'tool',
  style: 'realistic',
})

const object = await client.objects.get(id)
await client.objects.update(id, { styleLock: false, expectedUpdatedAt: object.updatedAt })

nodaro objects create "Antique Lantern" --node-id scripted \
  --description "Weathered brass lantern with hand-engraved filigree" \
  --category tool --style realistic

nodaro objects update <id> --style-lock false

만들기는 { id }를 반환합니다. 업데이트는 { id, updatedAt }을 반환합니다.

스타일 고정의 효과

• 켜짐(기본값). 모든 앵글, 재질, 변형이 승인된 대표 이미지에서 생성됩니다. 베리언트는 비율, 실루엣, 특징적인 디테일을 유지합니다. 오브젝트를 사용하는 노드는 기준 설명도 받습니다. 모든 샷에서 같은 물건으로 보여야 하는 경우에 사용하세요.
• 꺼짐. 베리언트가 텍스트만으로 생성됩니다. 노드는 여전히 기준 설명을 받지만 참고용일 뿐이므로, 모델이 디자인을 새롭게 해석할 수 있습니다. 다른 안을 탐색하거나 룩을 비교할 때 사용하세요.

대표 이미지 후보 생성

POST /v1/generate-object는 후보마다 작업을 하나씩 시작하고, 후보당 ID가 하나씩 든 jobIds를 즉시 반환합니다. 후보가 하나인 요청은 jobId도 반환합니다. 작업 API로 작업을 폴링하세요.

attachToObjectId와 count 1을 함께 보내면 작업이 완료될 때 결과가 오브젝트의 대표 이미지가 됩니다. 후보가 여러 개이면 아무것도 연결되지 않습니다. 마음에 드는 후보를 승인하세요.

curl -X POST https://app.nodaro.ai/v1/generate-object \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Antique Lantern", "count": 4 }'

const { jobIds } = await client.objects.generate({
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  count: 4,
})

nodaro objects generate --name "Antique Lantern" --count 1 \
  --attach-to-object-id <id> --watch

{
  "jobIds": [
    "5e2a8c1f-3b7d-4f9a-a6c2-8d1e4b7f0a3c",
    "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d",
    "7a4c1e3b-5d9f-4b2c-c8e4-1f3a6d9b2c5e",
    "8b5d2f4c-6e1a-4c3d-d9f5-2a4b7e1c3d6f"
  ]
}

seedPromptHint는 generate-object-asset과 generate-object-motion에서도 받습니다. 피커 노드를 연결하지 않고도 탈것이나 재질 같은 카탈로그 선택을 프롬프트에 조합할 수 있습니다.

베리언트 생성

POST /v1/generate-object-asset은 베리언트 하나를 생성하고 { jobId }를 반환합니다. 작업이 완료될 때 버킷에 { name: attachName, url }을 추가하려면 attachToObjectId, attachToColumn, attachName을 보내세요.

curl -X POST https://app.nodaro.ai/v1/generate-object-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "assetType": "materials",
    "variant": "gold",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachToColumn": "materials",
    "attachName": "gold"
  }'

await client.objects.generateAsset({
  name: 'Antique Lantern',
  assetType: 'variations',
  variant: 'weathered',
  attachToObjectId: id,
  attachToColumn: 'variations',
  attachName: 'weathered',
})

nodaro objects generate-asset --asset-type materials --variant gold \
  --attach-to-object-id <id> --attach-to-column materials --watch

대표 이미지 애니메이션

POST /v1/generate-object-motion은 오브젝트 이미지를 느린 회전, 호버, 드론 오빗 같은 짧은 카메라 무브 클립으로 만듭니다. 클립은 B롤이나 더 긴 동영상의 시작으로 사용하세요. 이 라우트는 { jobId }를 반환합니다.

sourceImageUrl은 필수이며 대체값이 없으므로, 승인된 대표 이미지를 전달하세요. attachToObjectId와 attachName을 보내면 클립이 완료될 때 motionClips에 추가됩니다. 컬럼은 보내지 않습니다.

curl -X POST https://app.nodaro.ai/v1/generate-object-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "motionPrompt": "slow 360 rotation, soft golden rim light",
    "sourceImageUrl": "https://cdn.nodaro.ai/objects/lantern-main.png",
    "provider": "kling-turbo",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachName": "rotate-360"
  }'

const lantern = await client.objects.get(id)

await client.objects.generateMotion({
  name: 'Antique Lantern',
  motionPrompt: 'slow 360 rotation, soft golden rim light',
  sourceImageUrl: lantern.sourceImageUrl!,
  provider: 'kling-turbo',
  attachToObjectId: id,
  attachName: 'rotate-360',
})

nodaro objects generate-motion --name "Antique Lantern" \
  --motion-prompt "slow 360 rotation, soft golden rim light" \
  --source-image-url "https://cdn.nodaro.ai/objects/lantern-main.png" \
  --provider kling-turbo --attach-to-object-id <id> --attach-name "rotate-360" --watch

클립 가격은 모델의 이미지-동영상 변환 가격입니다.

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

대표 이미지 승인

POST /v1/objects/:id/approve-main-image는 완료된 후보를 대표 이미지로 설정하고, 같은 호출에서 canonicalDescription을 작성합니다. 이후 프롬프트가 오브젝트를 설명할 때 쓰는 텍스트입니다. 본문은 { candidateJobId, expectedUpdatedAt? }이며, 후보는 내 소유의 completed 작업이어야 합니다.

이 라우트는 { sourceImageUrl, canonicalDescription }을 반환합니다. 설명 작성에 실패해도 대표 이미지는 설정되며, canonicalDescription은 빈 문자열이 됩니다. SDK는 대신 null을 반환합니다. 다시 시도하려면 POST /v1/objects/:id/llm-caption을 호출하세요. 이 라우트는 { canonicalDescription }을 반환하고, 설명을 작성할 수 없으면 502로, 아직 대표 이미지가 없으면 400 main_image_required로 응답합니다. expectedUpdatedAt은 받지 않으므로 언제든 안전하게 반복할 수 있습니다.

curl -X POST https://app.nodaro.ai/v1/objects/2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d" }'

const approved = await client.objects.approveMainImage(id, jobIds[1])
if (approved.canonicalDescription === null) {
  await client.objects.recaption(id)
}

nodaro objects approve-main-image <id> --candidate-job-id <jobId>
nodaro objects recaption <id>

오브젝트 보관, 복원, 삭제

• 보관은 { success: true, archived: true }를 반환합니다. 이미 보관된 오브젝트를 보관하면 아무것도 바뀌지 않습니다.
• 복원은 { id, name }을 반환합니다. 대소문자를 무시하고 같은 이름의 활성 오브젝트가 있으면 Nodaro가 (restored) 접미사를 붙이고 새 이름을 반환합니다.
• 영구 삭제는 { success: true, permanent: true }를 반환하고, 오브젝트와 오브젝트가 참조하는 파일 중 내 파일을 모두 제거합니다. 대표 이미지, 베리언트, 클립, 레퍼런스 사진이 모두 포함됩니다. 다른 사용자의 생성 작업이 만든 파일이나, 다른 사용자의 업로드 폴더 또는 라이브러리에 있는 파일은 저장소에 남습니다. 그런 파일은 내 저장 용량에 포함된 적이 없으므로 돌려받는 용량도 없습니다. 영구 삭제는 보관된 오브젝트에서만 작동하며, 활성 오브젝트는 400 not_archived를 반환합니다. 먼저 보관한 다음 삭제하세요.

앱 실행 시 베리언트 선택

오브젝트/소품 에셋 노드가 있는 워크플로를 앱으로 게시하면 오브젝트가 앱의 입력 중 하나가 됩니다. 해당 실행에서 베리언트를 오브젝트의 대표 이미지로 쓰려면 "materials/gold"처럼 "<bucket>/<variant>"를 전달하세요. 베리언트 이름은 소문자로 쓰고 공백은 하이픈으로 바꾸세요. polished-brass는 Polished Brass라는 베리언트와 일치합니다. 알 수 없는 버킷이나 베리언트는 대표 이미지로 대체됩니다. 앱 실행은 워크플로를 참조하세요.

다른 생성에서 오브젝트 사용

오브젝트의 에셋 URL을 이미지 생성 또는 동영상 생성에 레퍼런스 이미지로 전달하세요. 코드에서는 명시적인 URL이 가장 간단합니다. 워크플로에서는 오브젝트 노드를 이미지 노드에 연결하거나, 프롬프트에서 베리언트를 멘션하세요. 예를 들어 Lantern이라는 오브젝트라면 @lantern:1:materials/gold입니다. 멘션 없이 오브젝트를 연결하면 Nodaro는 프롬프트에서 베리언트 이름도 찾습니다. 프롬프트에 “gold finish”(금색 마감)가 있으면 materials/gold가 선택됩니다. 오브젝트를 참조하세요.

MCP에서 사용

오브젝트를 만들고, 업데이트하고, 보관하고, 복원하고, 삭제하는 MCP 도구는 없습니다. generate_object가 오브젝트를 만들며, 나머지 변경은 REST, SDK 또는 CLI로 합니다. MCP 도구 레퍼런스를 참조하세요.

크레딧

오류