コミュニティライブラリ

コミュニティライブラリ API を使うと、Nodaro インスタンスで共有されているキャラクター、ロケーション、オブジェクトのカタログを閲覧し、掲載アイテムを自分のライブラリに複製できます。カタログはキュレーションされています。インスタンスの管理者が掲載アイテムを公開し、ログインしているユーザーは誰でも、掲載アイテムを検索、お気に入り登録、複製、通報できます。

このライブラリは、複数ユーザー向けの機能です。Nodaro Cloud と、セルフホスティングの Business エディションで利用できます。Community エディションのインスタンスでは、これらのルートは登録されておらず、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 にも含まれていません。コミュニティライブラリを参照してください。

エラー