סקירה כללית של ה-REST API

ה-REST API של Nodaro הוא ממשק ה-HTTP של Nodaro: הוא מריץ תהליכים ורכיבים בודדים, מדווח על הסטטוס של המשימות שלהם, שומר את המדיה שלכם ומנהל דמויות, ערכות וסביבות עבודה. הבקשות והתגובות הן JSON על גבי HTTPS, וכל בקשה כוללת אסימון Bearer. אותו API משרת את Nodaro Cloud ואת ההתקנות באירוח עצמי, וה-SDK ל-TypeScript וה-CLI הם לקוחות דקים שלו.

כתובת הבסיס

כל נתיב מתחיל ב-/v1/, למשל https://app.nodaro.ai/v1/nodes. חלק מנקודות הקצה קיימות רק ב-Nodaro Cloud, כגון קרדיטים וארגונים, ובמהדורות אחרות הן מחזירות 404. בכל דף מצוין מתי נקודת קצה מוגבלת.

אימות

שלחו Authorization: Bearer <token> בכל בקשה. לחשבון שלכם, השתמשו באסימון API אישי (ndr_…) מהדף הגדרות › מפתחות API. כשהמוצר שלכם פועל בשם משתמשי Nodaro אחרים, השתמשו באסימון גישה של OAuth (ndr_app_…), ובהתקנה של מהדורת Community, ב-JWT של הסשן שלכם. כמה נקודות קצה של גילוי, כגון GET /v1/nodes ו-GET /v1/models, לא צריכות אסימון בכלל. כדי ליצור אסימון, ראו את דף ה-API אימות.

הקריאה הראשונה שלכם

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

export NODARO_API_KEY="ndr_..."

# 1. Start the job
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "a snow leopard on a mountain ridge at dawn",
        "provider": "nano-banana-pro",
        "aspectRatio": "16:9"
      }'
# {"jobId":"0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10"}

# 2. Poll the job until its status is "completed"
curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
    "status": "completed",
    "progress": 100,
    "output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
    "error_message": null
  }
}

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

// Starts the job and polls it until it finishes.
const output = await client.nodes.runAndWait('generate-image', {
  prompt: 'a snow leopard on a mountain ridge at dawn',
  provider: 'nano-banana-pro',
  aspectRatio: '16:9',
})
console.log(output.imageUrl)

nodaro nodes run generate-image \
  --param prompt="a snow leopard on a mountain ridge at dawn" \
  --param provider=nano-banana-pro \
  --param aspectRatio=16:9 \
  --watch --json | jq -r '.output_data.imageUrl'

אותו דפוס עובד בכל רכיב יצירה: קריאה לנתיב POST /v1/<node-type> עם ההגדרות של הרכיב, ואז תשאול של המשימה. ראו את דף ה-API הרצת רכיב יחיד.

מוסכמות של בקשות ותגובות

• שולחים JSON ומקבלים JSON. שלחו את גוף הבקשה כ-JSON עם Content-Type: application/json. העלאות של קבצים הן החריג: הן משתמשות ב-multipart/form-data.
• המזהים הם UUID. בקשה עם מזהה פגום נדחית עם 400 validation_error.
• רוב התגובות עטופות ב-data. קריאה מחזירה { "data": … }, ומחיקה או ביטול מחזירים { "success": true }. נקודות הקצה של התהליכים מדור קודם, תחת /v1/api/, מחזירות את המטען שלהן ישירות.
• יצירות מחזירות מזהה משימה. הנתיב POST /v1/<node-type> מחזיר { "jobId": "…" }, ולפעמים גם adjustments או warnings לצדו.
• רשימות משתמשות ב-cursor. רשימה מחזירה cursor, בדרך כלל nextCursor (או next ב-GET /v1/jobs). כדי לקבל את העמוד הבא, שלחו אותו בחזרה כ-?cursor=. כשה-cursor הוא null, אין עוד שורות. ה-cursor הוא ערך אטום: אף פעם אל תפענחו אותו ואל תבנו אחד בעצמכם.
• שני סגנונות של שמות שדות. אובייקטים של משימות משתמשים ב-snake_case, כגון output_data ו-created_at. תהליכים, רשומות הרצה ורוב המשאבים האחרים משתמשים ב-camelCase.
• התגובות מתרחבות. שדות חדשים נוספים עם הזמן. התעלמו משדות שאתם לא מכירים, במקום להיכשל בגללם.
• לכל השגיאות יש אותו מבנה. קריאה שנכשלת מחזירה סטטוס HTTP ו-{ "error": { "code": "…", "message": "…" } }. פעלו לפי code. ראו את דף ה-API שגיאות.

שתי כותרות אופציונליות משנות את האופן שבו בקשה מטופלת:

סינכרוני או אסינכרוני

רוב העבודה ב-Nodaro נמשכת בין כמה שניות לכמה דקות, ולכן ה-API אסינכרוני. נתיב של יצירה עונה מיד עם jobId, והרצת תהליך עונה 202 Accepted עם executionId. אחר כך בודקים את הסטטוס של המשימה או של רשומת ההרצה כל 2–5 שניות, עד שהיא מגיעה לסטטוס סופי. בתהליך שאתם מצפים שיסתיים בפחות מדקה, הנתיב POST /v1/api/run?wait=true משאיר את החיבור פתוח עד 600 שניות ומחזיר את התוצאה. כמה נתיבים עונים באופן סינכרוני, כגון רכיבי טקסט שרצים מיד, עיבוד מדיה חינמי והקריאה ל-LLM עם פלט מובנה. ראו בדף ה-API סינכרוני או אסינכרוני לפרטים. כדי לוותר על תשאול של משימות, רשמו נקודת קצה של Webhook: Nodaro שולח אז לשרת שלכם אירוע חתום בכל פעם שאחת מהמשימות שלכם מסתיימת או נכשלת.

נקודות קצה לפי תחום

הרצה

משאבים

חשבון

מדריך

מגבלות ושגיאות

אסימון API אישי מאפשר כברירת מחדל 30 בקשות לדקה, ועד 120, בנקודות הקצה של הרצת תהליכים ושל רשימת תהליכים, ולכמה נתיבים יש מגבלות משלהם. בדיקות סטטוס לא נספרות במגבלה של האסימון. תגובת 429 פירושה שצריך להאט ולנסות שוב, ולהאריך את ההמתנה אקספוננציאלית לפני כל ניסיון; תגובת 4xx פירושה שצריך לתקן את הבקשה לפני ניסיון חוזר; תגובת 5xx היא בדרך כלל זמנית. ראו את דפי ה-API מגבלות קצב ושגיאות.

לקוחות לשפה שלכם

• TypeScript ו-JavaScript: npm install @nodaro/sdk. ה-SDK עוטף את נקודות הקצה האלה בטיפוסים, בשגיאות עם טיפוס ובפונקציות עזר לתשאול.
• הטרמינל ו-CI: npm install -g @nodaro/cli. ה-CLI מריץ תהליכים, אפליקציות ורכיבים בודדים, עם --watch ו---json.
• כל שפה אחרת: צרו לקוח ממפרט OpenAPI, או שלחו בקשות HTTPS רגילות.
• עוזרי AI: חברו את שרת ה-MCP במקום לכתוב קוד.