# コミュニティライブラリ

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

Source: https://nodaro.ai/ja/docs/developers/api/community

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

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

## エンドポイント
| メソッド | パス | 説明 |
| --- | --- | --- |
| `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_type` | `character`、`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` です。

| クエリパラメーター | 説明 |
| --- | --- |
| `entityType` | `character`、`location`、`object` のいずれかです。 |
| `q` | タイトル、説明、タグを対象にした全文検索です。 |
| `category` | 1 つのカテゴリーだけに絞り込みます。 |
| `sort` | `newest`（デフォルト）か `popular` です。`popular` では、複製された回数の多い順に並びます。 |
| `limit` | ページサイズです。デフォルトは 20、最大は 50 です。 |
| `cursor` | 前のページの `nextCursor` です。 |

**curl**

```bash
curl "https://app.nodaro.ai/v1/community/browse?entityType=character&sort=popular&limit=20" \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

**TypeScript SDK**

```ts

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,
})
```

```json
{
"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**

```bash
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" }'
```

**TypeScript SDK**

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

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

新しい ID は、[キャラクター](https://nodaro.ai/docs/developers/api/characters)、[ロケーション](https://nodaro.ai/docs/developers/api/locations)、[オブジェクト](https://nodaro.ai/docs/developers/api/objects)の各 API で使います。

## 掲載アイテムをお気に入りに登録する
`POST /v1/community/listings/:id/favorite` は、お気に入りの登録と解除を切り替え、`{ favorited }` を返します。値は、登録した後は `true`、解除した後は `false` です。

```ts
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` | 掲載アイテムに、そのほかの問題がある場合です。 |

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

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

## 公開はキュレーション制
カタログは、インスタンスの管理者がキュレーションしています。掲載アイテムの公開は、公開 API にも SDK にも含まれていません。[コミュニティライブラリ](https://nodaro.ai/docs/guides/community-library)を参照してください。

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

## Frequently asked questions

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

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

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

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

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

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

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

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