NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
REST API

コミュニティライブラリ

REST API で、コミュニティライブラリの共有キャラクター、ロケーション、オブジェクトを閲覧、検索、お気に入り登録、複製します。掲載アイテムを通報して、モデレーションを依頼することもできます。

Nodaro Cloud · Business エディション で利用できます

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

このライブラリは、複数ユーザー向けの機能です。Nodaro Cloud と、セルフホスティングの Business エディションで利用できます。Community エディションのインスタンスでは、これらのルートは登録されておらず、404 を返します。ルートには Bearer トークンを使います。個人用 API トークン(ndr_…)、OAuth アプリのトークン(ndr_app_…)、セッショントークンのいずれかです。認証を参照してください。

公開作品を許可していないデプロイ環境では、掲載は提供されません。GET /v1/community/browse と GET /v1/community/favorites は空のリストを返し、掲載のカード(GET /v1/community/detail/:slug)、詳細のすべて、クローンは 404 not_found を返します。

エンドポイント

メソッドパス説明
GET/v1/community/browse公開されている掲載アイテムを、1 ページずつ一覧表示します。
GET/v1/community/detail/:slugスラッグを指定して、1 件の掲載アイテムを取得します。
GET/v1/community/favoritesお気に入りに登録した掲載アイテムを取得します。
POST/v1/community/listings/:id/clone掲載アイテムを自分のライブラリにコピーします。
POST/v1/community/listings/:id/favoriteお気に入りを追加または解除します。
POST/v1/community/listings/:id/report掲載アイテムを通報して、モデレーションを依頼します。

掲載アイテムの内容

読み取り用のルートはすべて、次の公開フィールドだけを含む掲載アイテムを返します。

フィールド説明
id, slug掲載アイテムの ID とスラッグです。ID は書き込み用のルートで、スラッグは詳細のルートで使います。
entity_typecharacter、location、object のいずれかです。
title, description, category, style, tags管理者が公開時に入力した内容です。
creator_display_name掲載アイテムを公開した人です。
preview_media_url, preview_imagesプレビュー画像と、画像のギャラリーです。
clone_count, favorite_count掲載アイテムが複製された回数と、お気に入りに登録された回数です。
created_at掲載アイテムが公開された日時です。

GET /v1/community/browse は { data: Listing[], nextCursor } を返します。次のページを取得するには、nextCursor を cursor として渡します。結果がそれ以上ない場合、nextCursor は null です。

クエリパラメーター説明
entityTypecharacter、location、object のいずれかです。
qタイトル、説明、タグを対象にした全文検索です。
category1 つのカテゴリーだけに絞り込みます。
sortnewest(デフォルト)か popular です。popular では、複製された回数の多い順に並びます。
limitページサイズです。デフォルトは 20、最大は 50 です。
cursor前のページの nextCursor です。
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 } で、この値は掲載アイテムの種類と一致している必要があります。

  • リンクではなく、コピーです。掲載アイテムの画像とクリップは、あなた自身のストレージにコピーされます。その後、元の掲載アイテムが変更されたり、掲載停止になったりしても、コピーには影響しません。
  • 自分のものになります。複製したものは、通常のキャラクター、ロケーション、オブジェクトです。名前の変更、編集、アセットの再生成、削除を自由に行えます。
  • 名前は重複しません。同じ名前のものがすでにある場合、複製には、同じ名前の後に番号を付けた名前(たとえば「ランタン 2」)が付けられます。
  • ストレージを使います。アカウントがストレージの上限を超えている場合、複製は 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 } で、値は次のいずれかです。

reason使う場面
real_person_no_consent掲載アイテムが、同意していない実在の人物を描写している場合です。
inappropriate掲載アイテムに、不適切なコンテンツが含まれている場合です。
ip_violation掲載アイテムが、他者の知的財産権を侵害している場合です。
other掲載アイテムに、そのほかの問題がある場合です。
await client.community.report(listingId, 'real_person_no_consent')

通報の後、掲載アイテムが掲載停止になることがあります。ユーザーがすでに複製したコピーは、それぞれのライブラリに残ります。

Nodaro Keepers:共有カタログ

Nodaro Keepers は、すぐに使えるキャラクター、クリーチャー、ロケーション、オブジェクトを集めた、誰でも使える棚です。棚のアイテムは、プラットフォームの管理者が選びます。コミュニティライブラリと同じく、Nodaro Cloud と Business エディションにあります。

アイテムを使うと、掲載アイテムの複製と同じルールで、自分のアカウントにコピーされます。

  • コピーは自分自身の行です。スタジオで編集でき、ほかのアイテムと一緒に一覧に表示され、削除もできます。
  • レンダリングの一貫性を保つものが一緒にコピーされます。公開されているテキスト、メイン画像、アングル、表情、ポーズなどのバリエーションのアセットです。すべてのファイルは自分のストレージにコピーされ、その容量を使います。
  • ボイス:プリメイドまたはライブラリのボイスは、そのまま引き継がれます。カスタムまたはクローンのボイスは、名前とサンプルだけになります。
  • 引き継がれないもの:所有者のピッカーの選択、リファレンス写真、学習済みモデルのフィールドです。
  • 元のアイテムは変わりません。後から元のアイテムが変更されてもコピーには反映されず、棚から外されてもコピーは削除されません。

棚の読み取りとアイテムのコピーに、クレジットはかかりません。

メソッドパス内容
GET/v1/keepers/catalog棚です。公開されていて、トークンは不要なので、ゲストも閲覧できます。
POST/v1/keepers/catalog/:kind/:id/copyアイテムを 1 件、自分のアカウントにコピーします。

棚を読み取る。GET /v1/keepers/catalog は、kind(character、creature、location、object のいずれか)、limit(1〜200、デフォルトは 50)、cursor(前のページの next)を受け付けます。kind がない場合、ページはこの順番で種類をたどります。{ data, next } を返します。各アイテムは { id, kind, name, description, imageUrl, previewUrl, category, sort, createdAt } です。

  • previewUrl は、タイル用の、幅 480 ピクセルの imageUrl のコピーです。
  • category は棚の見出しで、sort は棚の並び順です。小さい値が先で、同じ値では新しいものが先です。
  • 棚には表示用のフィールドだけが含まれます。ユーザー ID、プロンプト、リファレンス写真、学習済みモデルのフィールドが含まれることはありません。
  • 読み取れない cursor には 400 validation_error が返り、最初のページが返ることはありません。
  • 応答は 60 秒間キャッシュされるので、棚の変更は 1 分以内に表示されます。1 つのアドレスから棚を読み取れるのは 1 分あたり 60 回までで、それを超えると 429 が返ります。

アイテムをコピーする。POST /v1/keepers/catalog/:kind/:id/copy は { id, name, kind, created } を返します。id は自分自身の行です。GET /v1/characters/:id や、ほかのアセットのルートで読み取れます。コピーは、新しいキャンバス ID を付けて、デフォルトのプロジェクトに入ります。

  • コピーは、1 人につき 1 アイテム 1 件です。2 回目の呼び出しや、同時に行った 2 回の呼び出しは、同じコピーを created: false で返します。
  • アーカイブしたコピーは、アーカイブが解除されて戻ります。
  • すでに持っているコピーは、アイテムが棚に残っているかどうかに関係なく、自分のものです。
  • OAuth アプリのトークンには、assets:write スコープが必要です。
ステータスコード説明
404not_foundアイテムが棚になく、そのコピーも持っていません。
413storage_limit_exceededファイルがストレージに収まりません。何も保存されません。
403personal_space_disabledコピーが入る個人スペースを、組織が閉じています。
# Anyone can read the shelf
curl "https://app.nodaro.ai/v1/keepers/catalog?kind=character&limit=20"

# A signed-in user copies one item
curl -X POST "https://app.nodaro.ai/v1/keepers/catalog/character/$ITEM_ID/copy" \
  -H "Authorization: Bearer $NODARO_API_KEY"
{ "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e", "name": "Mira", "kind": "character", "created": true }

キャラクター、クリーチャー、ロケーション、オブジェクトを読み取ると、どれにも棚での状態が catalog、catalogSort、catalogCategory として含まれます。自分の行と、すべてのコピーでは false、0、null です。

公開はキュレーション制

カタログは、インスタンスの管理者がキュレーションしています。掲載アイテムの公開は、公開 API にも SDK にも含まれていません。コミュニティライブラリを参照してください。

エラー

ステータスコード説明
400validation_errorフィールドが不足しているか、無効です。
401unauthorizedトークンがないか、無効か、取り消されています。
403insufficient_scope複製に使った OAuth アプリのトークンに、assets:write がありません。
404not_found掲載アイテムが存在しないか、掲載停止になっています。または、インスタンスが Community エディションです。
413storage_limit_exceededアカウントがストレージの上限を超えています。

よくある質問

複製した掲載アイテムは、元の掲載アイテムとつながっていますか?

いいえ。複製すると、掲載アイテムの画像とクリップが、あなた自身のストレージにコピーされます。コピーは自由に編集でき、元の掲載アイテムが変更されたり、掲載停止になったりしても残ります。

API で、自分のキャラクターをコミュニティライブラリに公開できますか?

いいえ。カタログは、インスタンスの管理者がキュレーションしています。API でできるのは、掲載アイテムの閲覧、お気に入り登録、複製、通報で、ログインしているユーザーなら誰でも使えます。

自分のインスタンスで、コミュニティライブラリ API が 404 を返すのはなぜですか?

コミュニティライブラリは、Business エディションと Nodaro Cloud の、複数ユーザー向けの機能です。Community エディションのインスタンスはこれらのルートを登録しないため、すべての呼び出しが 404 を返します。

ストレージがいっぱいのときに掲載アイテムを複製すると、どうなりますか?

複製は 413 storage_limit_exceeded で拒否され、何もコピーされません。ストレージに空きを作ってから、もう一度試してください。

Nodaro Keepers とは何ですか?

Nodaro Keepers は、すぐに使えるキャラクター、クリーチャー、ロケーション、オブジェクトを集めた共有の棚です。GET /v1/keepers/catalog はトークンなしで棚を読み取り、POST /v1/keepers/catalog/:kind/:id/copy はアイテムを無料で自分のアカウントにコピーします。

最終更新

目次