# ספריית הקהילה

> עיון, חיפוש, הוספה למועדפים ושכפול של דמויות, מיקומים ואובייקטים משותפים מספריית הקהילה ב-REST API, ודיווח על פריט לבדיקה.

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

**ה-API של ספריית הקהילה** מאפשר לעיין בקטלוג המשותף של דמויות, מיקומים ואובייקטים במופע ה-Nodaro שלכם, ולשכפל פריט לספרייה שלכם. הקטלוג נבחר בקפידה: מנהלי המופע מפרסמים את הפריטים, וכל משתמש מחובר יכול לחפש אותם, להוסיף אותם למועדפים, לשכפל אותם ולדווח עליהם.

הספרייה היא יכולת מרובת משתמשים. היא קיימת ב-Nodaro Cloud ובמהדורת Business באירוח עצמי; במופע של מהדורת Community הנתיבים האלה לא רשומים ומחזירים `404`. הנתיבים מקבלים אסימון Bearer: אסימון API אישי (`ndr_…`), אסימון של אפליקציית OAuth (`ndr_app_…`) או אסימון הסשן שלכם. ראו את דף ה-API [אימות](https://nodaro.ai/docs/developers/api/authentication).

## נקודות קצה
| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `GET` | `/v1/community/browse` | רשימת הפריטים הציבוריים, עמוד אחד בכל פעם. |
| `GET` | `/v1/community/detail/:slug` | קבלת פריט אחד לפי המזהה בכתובת שלו. |
| `GET` | `/v1/community/favorites` | הפריטים שהוספתם למועדפים. |
| `POST` | `/v1/community/listings/:id/clone` | העתקת פריט לספרייה שלכם. |
| `POST` | `/v1/community/listings/:id/favorite` | הוספה למועדפים או הסרה מהם. |
| `POST` | `/v1/community/listings/:id/report` | דיווח על פריט לבדיקה. |

## מה יש בפריט
כל נתיבי הקריאה מחזירים פריטים עם השדות הציבוריים האלה בלבד.

| שדה | מה יש בו |
| --- | --- |
| `id`, `slug` | המזהה של הפריט, שנתיבי הכתיבה משתמשים בו, והמזהה בכתובת (slug) שלו, שנתיב הפרטים משתמש בו. |
| `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`; כשאין עוד תוצאות, הערך שלו הוא `null`.

| פרמטר שאילתה | מה הוא עושה |
| --- | --- |
| `entityType` | `character`, `location` או `object`. |
| `q` | חיפוש טקסט מלא בכותרת, בתיאור ובתגיות. |
| `category` | רק קטגוריה אחת. |
| `sort` | `newest` (ברירת המחדל) או `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 }`: הסוג והמזהה של הדמות, המיקום או האובייקט החדשים שלכם. גוף הבקשה הוא `{ entityType }`, והערך חייב להתאים לסוג של הפריט.

- **עותק, לא קישור.** התמונות והקליפים של הפריט מועתקים לאחסון שלכם. שינויים מאוחרים במקור, או הסרה של הפריט מהספרייה, לא משפיעים על העותק שלכם.
- **העותק שייך לכם.** העותק הוא דמות, מיקום או אובייקט רגיל. אפשר לשנות את השם שלו, לערוך אותו, ליצור מחדש את התמונות שלו או למחוק אותו.
- **אין התנגשות בין שמות.** אם כבר יש לכם נכס עם אותו שם, העותק מקבל את אותו שם ואחריו מספר, למשל ״פנס 2״.
- **העותק תופס מקום באחסון שלכם.** כשהחשבון שלכם חורג ממגבלת האחסון, השכפול נדחה עם `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" }
```

השתמשו במזהה החדש עם הנתיבים שבדפי ה-API [דמויות](https://nodaro.ai/docs/developers/api/characters), [מיקומים](https://nodaro.ai/docs/developers/api/locations) או [אובייקטים](https://nodaro.ai/docs/developers/api/objects).

## הוספת פריט למועדפים
הנתיב `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')
```

אפשר להסיר פריט מהספרייה אחרי דיווח. עותקים שמשתמשים כבר שכפלו נשארים בספריות שלהם.

## Nodaro Keepers: הקטלוג המשותף
**Nodaro Keepers** הוא מדף של דמויות, יצורים, מיקומים ואובייקטים מוכנים שכולם יכולים להשתמש בהם. מנהלי הפלטפורמה בוחרים את הפריטים שעליו. כמו ספריית הקהילה, הוא קיים ב-Nodaro Cloud ובמהדורת Business.

שימוש בפריט מעתיק אותו לחשבון שלכם, לפי אותו כלל כמו שכפול פריט מספריית הקהילה:

- **העותק הוא רשומה שלכם.** אפשר לערוך אותו באולפן, הוא מופיע ברשימה עם שאר הפריטים שלכם, ואפשר למחוק אותו.
- **העותק כולל את מה ששומר על עקביות התוצאות שלו:** הטקסט הציבורי, התמונה הראשית והווריאנטים, כגון זוויות, הבעות ותנוחות. כל קובץ מועתק לאחסון שלכם ונספר בו.
- **קולות:** קול מוכן מראש או קול מהספרייה עובר לעותק. מקול מותאם אישית או משוכפל נשארים רק השם והדוגמה שלו.
- **מה שאף פעם לא עובר:** הבחירות של הבעלים בבוררים, תמונות הייחוס ושדות המודל המאומן.
- **המקור לא משנה את העותקים.** שינוי מאוחר במקור לא מגיע לעותקים, והורדה שלו מהמדף לא מוחקת אף עותק.

קריאת המדף והעתקת פריט לא עולות קרדיטים.

| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `GET` | `/v1/keepers/catalog` | המדף. ציבורי: הנתיב לא דורש אסימון, ולכן גם אורח יכול לעיין בו. |
| `POST` | `/v1/keepers/catalog/:kind/:id/copy` | העתקת פריט אחד לחשבון שלכם. |

**קריאת המדף.** הנתיב `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` הוא עותק של `imageUrl` ברוחב 480 פיקסלים, לתצוגה באריח.
- השדה `category` הוא הכותרת על המדף, והשדה `sort` הוא הסדר על המדף: מהנמוך לגבוה, ואחר כך מהחדש לישן.
- במדף יש רק שדות תצוגה: אף פעם לא מזהה משתמש, פרומפט, תמונת ייחוס או שדה של מודל מאומן.
- על `cursor` שאי אפשר לקרוא מקבלים `400 validation_error`, ואף פעם לא את העמוד הראשון.
- התגובה נשמרת במטמון ל-60 שניות, ולכן שינוי במדף מופיע בתוך דקה. כתובת IP אחת יכולה לקרוא את המדף 60 פעמים בדקה, ובקשות נוספות נדחות עם `429`.

**העתקת פריט.** הנתיב `POST /v1/keepers/catalog/:kind/:id/copy` מחזיר `{ id, name, kind, created }`. השדה `id` מזהה את הרשומה שלכם: קבלו אותה עם [`GET /v1/characters/:id`](https://nodaro.ai/docs/developers/api/characters) ועם נתיבי הנכסים האחרים. העותק נכנס לפרויקט ברירת המחדל שלכם, עם מזהה קנבס חדש.

- **עותק אחד לכל אדם ולכל פריט.** קריאה שנייה, או שתי קריאות בבת אחת, מחזירות את אותו עותק עם `created: false`.
- עותק שהעברתם לארכיון חוזר מהארכיון.
- עותק שכבר יש לכם נשאר שלכם, בין שהפריט עדיין על המדף ובין שלא.
- אסימון של אפליקציית OAuth צריך את ההרשאה `assets:write`.

| סטטוס | קוד | משמעות |
| --- | --- | --- |
| `404` | `not_found` | הפריט לא נמצא על המדף, ואין לכם עותק שלו. |
| `413` | `storage_limit_exceeded` | הקבצים שלו לא נכנסים באחסון שלכם. שום דבר לא נשמר. |
| `403` | `personal_space_disabled` | הארגון שלכם סגר את המרחב האישי שאליו נכנסים העותקים. |

```bash
# 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"
```

```json
{ "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e", "name": "Mira", "kind": "character", "created": true }
```

בכל קריאה של דמות, יצור, מיקום או אובייקט חוזר גם מצב המדף של הנכס, בשדות `catalog`, `catalogSort` ו-`catalogCategory`. ברשומות שלכם ובכל עותק, הערכים שלהם הם `false`, `0` ו-`null`.

## הפרסום בידי המנהלים
מנהלי המופע בוחרים מה נכנס לקטלוג. פרסום פריט הוא לא חלק מה-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` | החשבון שלכם חורג ממגבלת האחסון. |

## שאלות נפוצות

### האם עותק משוכפל מקושר לפריט המקורי?

לא. השכפול מעתיק את התמונות והקליפים של הפריט לאחסון שלכם. העותק שייך לכם ואפשר לערוך אותו, והוא נשמר גם כשהפריט המקורי משתנה או מוסר מהספרייה.

### האם אפשר לפרסם דמות משלי בספריית הקהילה דרך ה-API?

לא. מנהלי המופע בוחרים מה נכנס לקטלוג. ה-API מאפשר לכל משתמש מחובר לעיין בפריטים, להוסיף אותם למועדפים, לשכפל אותם ולדווח עליהם.

### למה ה-API של ספריית הקהילה מחזיר 404 במופע שלי?

ספריית הקהילה היא יכולת מרובת משתמשים של Nodaro Cloud ושל מהדורת Business. מופע של מהדורת Community לא רושם את הנתיבים האלה, ולכן כל קריאה אליהם נדחית עם 404.

### מה קורה כשמשכפלים פריט והאחסון שלי מלא?

השכפול נדחה עם 413 storage_limit_exceeded, ושום דבר לא מועתק. פנו מקום באחסון ונסו שוב.

### מה זה Nodaro Keepers?

Nodaro Keepers הוא מדף משותף של דמויות, יצורים, מיקומים ואובייקטים מוכנים. הנתיב GET /v1/keepers/catalog מחזיר אותו בלי אסימון, והנתיב POST /v1/keepers/catalog/:kind/:id/copy מעתיק פריט לחשבון שלכם בחינם.