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

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

הספרייה היא יכולת מרובת משתמשים. היא קיימת ב-Nodaro Cloud ובמהדורת Business באירוח עצמי; במופע של מהדורת Community הנתיבים האלה לא רשומים ומחזירים 404. הנתיבים מקבלים אסימון Bearer: אסימון API אישי (ndr_…), אסימון של אפליקציית OAuth (ndr_app_…) או אסימון הסשן שלכם. ראו את דף ה-API אימות.

נקודות קצה

מה יש בפריט

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

עיון וחיפוש

הנתיב GET /v1/community/browse מחזיר { data: Listing[], nextCursor }. כדי לקבל את העמוד הבא, שלחו את nextCursor בחזרה בפרמטר cursor; כשאין עוד תוצאות, הערך שלו הוא 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 }: הסוג והמזהה של הדמות, המיקום או האובייקט החדשים שלכם. גוף הבקשה הוא { 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" }

השתמשו במזהה החדש עם הנתיבים שבדפי ה-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')

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

Nodaro Keepers: הקטלוג המשותף

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

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

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

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

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

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

# 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. ראו את המדריך ספריית הקהילה.

שגיאות