커뮤니티 라이브러리

커뮤니티 라이브러리 API로 Nodaro 인스턴스에 공유된 캐릭터, 장소, 오브젝트 카탈로그를 둘러보고, 게시물을 내 라이브러리로 복제할 수 있습니다. 카탈로그는 선별해 관리됩니다. 인스턴스 관리자가 게시물을 게시하고, 로그인한 모든 사용자는 게시물을 검색하고, 즐겨찾기에 추가하고, 복제하고, 신고할 수 있습니다.

라이브러리는 다중 사용자 기능입니다. Nodaro Cloud와 셀프 호스팅 Business 에디션에 있으며, Community Edition 인스턴스에서는 이 라우트가 등록되지 않아 404를 반환합니다. 인증에는 Bearer 토큰을 사용합니다. 개인 API 토큰(ndr_…), OAuth 앱 토큰(ndr_app_…), 또는 세션 토큰을 보내세요. 인증을 참조하세요.

엔드포인트

게시물에 담기는 정보

모든 읽기 라우트는 다음 공개 필드만 담은 게시물을 반환합니다.

둘러보기와 검색

GET /v1/community/browse는 { data: Listing[], nextCursor }를 반환합니다. 다음 페이지를 가져오려면 nextCursor를 cursor로 다시 보내세요. 결과가 더 없으면 nextCursor는 null입니다.

curl "https://app.nodaro.ai/v1/community/browse?entityType=character&sort=popular&limit=20" \
  -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 { data, nextCursor } = await client.community.browse({
  entityType: 'character',
  sort: 'popular',
  limit: 20,
})

{
  "data": [
    {
      "id": "e4b2d8f1-6a3c-4e9b-8d7f-1c5a3e9b2d6f",
      "entity_type": "character",
      "slug": "detective-mara",
      "title": "Detective Mara",
      "description": "Noir-styled investigator",
      "category": "people",
      "style": "realistic",
      "tags": ["noir", "detective"],
      "creator_display_name": "Nodaro Team",
      "preview_media_url": "https://cdn.nodaro.ai/community/detective-mara.png",
      "clone_count": 128,
      "favorite_count": 41,
      "created_at": "2026-08-30T14:02:11Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0zMCJ9"
}

GET /v1/community/detail/:slug는 { data: Listing }을 반환하며, 게시물이 없거나 내려간 경우에는 404 not_found를 반환합니다. GET /v1/community/favorites는 { data: Listing[] }을 반환합니다.

게시물 복제

POST /v1/community/listings/:id/clone은 게시물을 내 라이브러리로 복사하고 { entityType, id }를 반환합니다. 새로 생긴 캐릭터, 장소, 오브젝트의 종류와 id입니다. 본문은 { entityType }이며, 게시물의 종류와 일치해야 합니다.

• 링크가 아니라 복사본입니다. 게시물의 이미지와 클립이 내 저장 공간으로 복사됩니다. 이후 원본이 변경되거나 게시물이 내려가도 복사본에는 영향이 없습니다.
• 내 것입니다. 복제본은 일반 캐릭터, 장소, 오브젝트와 같습니다. 이름을 바꾸고, 편집하고, 에셋을 다시 생성하거나 삭제할 수 있습니다.
• 이름이 겹치지 않습니다. 같은 이름이 이미 있으면 복제본에 복사 접미사가 붙은 고유한 이름이 지정됩니다.
• 내 저장 공간을 사용합니다. 계정이 저장 공간 한도를 넘으면 복제가 413 storage_limit_exceeded로 거부됩니다.

OAuth 앱 토큰으로 복제하려면 assets:write 스코프가 필요합니다. 개인 API 토큰에는 스코프가 필요하지 않습니다.

curl -X POST https://app.nodaro.ai/v1/community/listings/e4b2d8f1-6a3c-4e9b-8d7f-1c5a3e9b2d6f/clone \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityType": "character" }'

const { id } = await client.community.clone(listingId, 'character')
const mara = await client.characters.get(id)

{ "entityType": "character", "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e" }

새 id는 캐릭터, 장소, 오브젝트 API에서 사용하세요.

게시물 즐겨찾기

POST /v1/community/listings/:id/favorite은 즐겨찾기를 켜거나 끄고 { favorited }를 반환합니다. 추가하면 true, 제거하면 false입니다.

const { favorited } = await client.community.favorite(listingId)
const { data: favorites } = await client.community.favorites()

게시물 신고

POST /v1/community/listings/:id/report는 관리자가 검토하도록 게시물을 신고하고 { ok: true }를 반환합니다. 본문은 { reason }이며, 값은 다음 중 하나입니다.

await client.community.report(listingId, 'real_person_no_consent')

신고 후 게시물이 내려갈 수 있습니다. 사용자가 이미 복제한 복사본은 각자의 라이브러리에 그대로 남습니다.

선별 방식의 게시

카탈로그는 인스턴스 관리자가 선별해 관리합니다. 게시물 게시는 공개 API나 SDK에 포함되지 않습니다. 커뮤니티 라이브러리를 참조하세요.

오류