העלאות

העלאות מכניסות תמונות, וידאו ואודיו משלכם לאחסון של Nodaro, כדי שכל רכיב יוכל להשתמש בהם לפי הכתובת שלהם. הנתיב POST /v1/upload שומר קובץ אחד ומחזיר את הכתובת שלו. נתיבים אחרים מעתיקים קובץ מכתובת URL, מייבאים סרטון מרשת חברתית, מקצצים קובץ שמור בחינם או מחזירים את המדיה ששמרתם.

נקודות קצה

העלאת קובץ

שלחו את הקובץ כ-multipart form data בשדה file. אפשר לשלוח גם type, עם הערך image, video או audio.

curl -s -X POST https://app.nodaro.ai/v1/upload \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -F "file=@portrait.png;type=image/png" \
  -F "type=image"

{
  "data": {
    "url": "https://…/portrait.png",
    "assetId": "5d6e7f80-91a2-4b3c-8d4e-5f60718293a4",
    "thumbnailUrl": "https://…/portrait-thumb.webp",
    "category": "image",
    "filename": "portrait.png",
    "mimeType": "image/png",
    "sizeBytes": 1482233,
    "r2Key": "…/portrait.png"
  }
}

// In a browser, file comes from an <input type="file">.
// In Node 20 or newer, build it from bytes:
import { readFile } from 'node:fs/promises'

const file = new File([await readFile('portrait.png')], 'portrait.png', { type: 'image/png' })
const upload = await client.uploads.upload(file)
console.log(upload.url) // pass it as imageUrl, videoUrl or audioUrl

ב-CLI אין פקודת העלאה. כדי להעתיק מהטרמינל לאחסון שלכם קובץ שכבר נמצא ברשת, השתמשו בפקודה nodaro media save <url>.

פורמטים וסוגי קבצים

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

• פרמטרים מוסרים. הסוג audio/webm;codecs=opus הופך ל-audio/webm.
• כתיבים חלופיים נפוצים ממופים לסוג התקני. הסוג audio/vnd.dlna.adts, ש-Windows משתמש בו לקובץ .aac רגיל, הופך ל-audio/aac, image/jpg הופך ל-image/jpeg ו-video/mov הופך ל-video/quicktime.
• סוג שלא אומר כלום נקבע לפי שם הקובץ. עם application/octet-stream, או בלי סוג בכלל, הסיומת קובעת: הקובץ clip.mp4 נשמר כ-video/mp4.

סוג שעדיין לא תואם לאף פורמט שמתקבל נדחה עם 400 validation_error, עם רשימת הפורמטים שמתקבלים. הסוג שהשרת קבע חוזר ב-mimeType, והקובץ מוגש איתו.

תמונות HEIC, HEIF ו-AVIF מומרות לפני שהן נשמרות. מעט דפדפנים מציגים את הפורמטים האלה, ומודלי התמונה לא מקבלים אותם. כל דרך העלאה של תמונות שומרת קובץ כזה כ-JPEG, או כ-PNG כשיש בתמונה שקיפות, והשדה mimeType מציין את הסוג השמור. דרכי ההעלאה האלה הן POST /v1/upload, POST /v1/upload/image, ההעלאה שמאחורי כלי ה-MCP prepare_image_upload ו-request_image_upload והייבוא בצד השרת של כתובת תמונה. דרך העלאה שנתנה את הכתובת של הקובץ לפני ההעלאה שומרת על הכתובת הזו, ורק סוג התוכן של הקובץ משתנה. ההמרה כוללת גם קובצי AVIF של 10 ביט ותמונות HEIC מ-iPhone. את שני אלה קורא מפענח שלא שומר על שקיפות, ולכן אזור שקוף בהם יוצא אטום. קובץ AVIF של 8 ביט שומר על השקיפות שלו. קובץ שאי אפשר לפענח בכלל נדחה עם 400.

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

כשהעלאה נדחית

שימוש בכתובת URL במקום העלאה

רוב הנתיבים מקבלים מדיה לפי כתובת URL, כגון imageUrl, videoUrl, audioUrl ו-referenceImageUrls, ולכן אין צורך להעלות קובץ שכבר נמצא ברשת. הכתובת חייבת להיות כתובת http או https ציבורית: כתובת שמפנה לכתובת ברשת פרטית, או שמשתמשת בסכמה אחרת, נדחית.

העתיקו את הקובץ לאחסון של Nodaro כשהכתובת זמנית, כמו קישור חתום שתוקפו מוגבל, או כשאתם רוצים שהקובץ יישאר זמין:

curl -s -X POST https://app.nodaro.ai/v1/save-to-storage \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mediaUrl": "https://example.com/clip.mp4", "filename": "clip.mp4", "mediaType": "video"}'
# {"jobId":"…"}  poll the job; its output carries the stored file

const { jobId } = await client.media.saveToStorage({
  mediaUrl: 'https://example.com/clip.mp4',
  filename: 'clip.mp4',
  mediaType: 'video',
})

nodaro media save https://example.com/clip.mp4 --filename clip.mp4 --type video --watch

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

ייבוא סרטון מרשת חברתית

הנתיב POST /v1/download-video מייבא לאחסון שלכם את הסרטון שמאחורי קישור לדף של סרטון, או סרטון מקישור ישיר לקובץ וידאו. שלחו את אישור זכויות התוכן של הקישור בשדה confirmationId (ראו את דף ה-API זכויות תוכן). הנתיב מחזיר downloadId, ולא מזהה משימה:

{ "url": "https://youtu.be/XXXX", "maxHeight": 720, "sectionStartSec": 30, "sectionEndSec": 90 }

• השדה maxHeight מגביל את הרזולוציה; השמיטו אותו כדי לקבל את הרזולוציה הטובה ביותר שזמינה. השדות sectionStartSec ו-sectionEndSec מורידים רק את החלק הזה של הסרטון, עם כ-3 שניות נוספות בכל צד, כי החיתוך נופל על פריימי מפתח. שלחו את שניהם או אף אחד מהם, וקצצו את התוצאה כשצריך חיתוך מדויק. עם exactSection: true, החלק נחתך במקום זאת בדיוק בטווח הזה, בלי שוליים.
• ייבוא של סרטון בלי רצועת אודיו נכשל, אלא אם שולחים requireAudio: false.
• כל חשבון יכול להריץ 4 ייבואים בבת אחת. ייבוא חמישי נדחה עם 429 too_many_downloads.
• הנתיב GET /v1/download-video/progress/:downloadId מזרים את ההתקדמות כאירועי שרת (SSE), בערך פעמיים בשנייה: { phase, percent, videoUrl?, thumbnailUrl?, error? }. הזרם מסתיים כשהסטטוס של הייבוא הוא completed, עם ה-videoUrl השמור, או failed, עם error. ההתקדמות נשמרת רק לזמן קצר אחרי שהייבוא מסתיים, ולכן התחילו לקרוא אותה מיד.
• הסרטון המוגמר נשמר בספרייה שלכם.

כדי לבדוק סרטון לפני שמייבאים אותו, הנתיב POST /v1/video-metadata עם { url } קורא את משך הסרטון, את הגודל ואת הכותרת שלו בלי להוריד אותו. מהטרמינל: הפקודות nodaro media download <url> --max-height 720 --watch ו-nodaro media metadata <url>. ראו את דף ה-API קול ומדיה לשאר כלי המדיה.

קיצוץ או חיתוך של קובץ שמור

הנתיב POST /v1/media/process מקצץ או חותך קובץ וידאו או אודיו שמור. הנתיב חינמי ועונה מיד, בלי משימה:

{
  "sourceUrl": "https://…/interview.mp4",
  "type": "video",
  "trim": { "startTime": 12.5, "endTime": 48 },
  "crop": { "x": 0, "y": 0, "width": 1080, "height": 1080 }
}

התגובה היא { "data": { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } }. השדה format קובע את פורמט הפלט: לווידאו mp4 או webm, לאודיו mp3, wav, m4a או aac. עם deleteSource: true, קובץ המקור נמחק אחר כך אם הוא שלכם ושום דבר אחר לא משתמש בו, כך שהגרסה המקוצצת מחליפה את המקור. ב-SDK, קראו ל-client.media.process(input). כדי לקצץ בתוך תהליך, השתמשו ברכיב קיצוץ וידאו, שעולה קרדיטים.

ייבוא תמונה מכתובת אינטרנט

הנתיב POST /v1/media/import-url עם גוף הבקשה { "url": "https://…" } מעתיק תמונה מכתובת אינטרנט לאחסון שלכם. הכתובת חייבת להיות http או https ולא פרטית, והגודל המרבי של התמונה הוא 20 MB. הפלטפורמה שומרת את הקובץ רק אם אפשר לפענח אותו כתמונה: JPEG, PNG, WebP או GIF. תמונת HEIC, HEIF או AVIF מומרת ל-JPEG או ל-PNG. העותק השמור נחשב להעלאה שלכם, והוא מוגש כך שאלמנט <canvas> בדפדפן יכול לקרוא את הפיקסלים שלו, למשל כדי לחתוך אותו.

התגובה היא { "data": { url, thumbnailUrl, assetId, mimeType, sizeBytes, filename, width, height } }. כשהייבוא נדחה, התשובה היא 400 validation_error על כתובת או פורמט שלא מתקבלים, 422 fetch_failed כשאי אפשר להגיע לכתובת ו-413 כשהתמונה גדולה מ-20 MB (file_too_large) או כשנפח האחסון שלכם מלא (storage_limit_exceeded). ב-SDK, קראו ל-client.uploads.importUrl(url). רכיב העלאת תמונה משתמש בייבוא הזה כשמדביקים קישור לתמונה.

מחיקת קובץ שכבר אין בו צורך

הנתיב POST /v1/media/discard עם גוף הבקשה { "url": "https://…" } מוחק קובץ שיצרתם זה עתה ושכבר אין לכם צורך בו. דוגמאות: הורדה מקישור שהחלפתם לפני שהשתמשתם בה, קטע מקוצץ שהוחלף בקטע חדש יותר ותמונה שייבאתם ואז ביטלתם. זו לא מחיקה כללית. הקובץ נמחק רק אם הוא שלכם, ורק אם /v1/download-video, /v1/media/process או ייבוא מכתובת URL יצרו אותו. בנוסף, הקובץ צריך להיות בן פחות מ-24 שעות, ואסור שמשימה כלשהי שלכם תשתמש בו, לא כפלט ולא כקלט, כמו ה-videoUrl של הרצה.

ב-SDK, קראו ל-client.media.discard({ url }).

ספריית המדיה שלכם

הנתיב GET /v1/library מחזיר את המדיה שלכם, מהחדש לישן. כברירת מחדל הוא מחזיר את הקבצים ששמרתם בספרייה שלכם, ובנוסף את הספרייה המשותפת. עם owned=true, הוא מחזיר במקום זאת כל קובץ שבבעלותכם: העלאות ויצירות, בין שנשמרו בספרייה ובין שלא.

התגובה היא { data, nextCursor, totalCount }. כל פריט כולל את id, type, filename, mimeType, sizeBytes, url, thumbnailUrl, metadata, isLibraryItem, uploadSource, source, sourceDetail, jobId ו-createdAt. השדה jobId הוא המשימה שיצרה את הקובץ, או null בהעלאה. בעמוד האחרון השדה nextCursor הוא null, והשדה totalCount, מספר הקבצים שתואמים, מגיע רק עם העמוד הראשון.

curl -s "https://app.nodaro.ai/v1/library?owned=true&type=image&q=poster" \
  -H "Authorization: Bearer $NODARO_API_KEY"

ב-SDK, קראו ל-client.library.list({ type: 'image', q: 'poster' }). כלי ה-MCP browse_uploads קורא את התצוגה של owned=true, עם אותו חיפוש לפי שם קובץ בארגומנט search שלו.

הנתיב POST /v1/library/save-generated עם { url, type } שומר קובץ בספרייה שלכם. קובץ באחסון של Nodaro מתקבל רק אם הוא שלכם: אחת היצירות שלכם, קובץ שהעליתם או קובץ בתיקיית ההעלאות שלכם. כל קובץ אחר באחסון של Nodaro נדחה עם 403 forbidden, בין שהוא קיים ובין שלא. קישור לכל אתר אחר נשמר כמו שהוא.

שליחת משתמש לקובץ אחד

כדי לשלוח משתמש מחובר לקובץ אחד בספריית הקבצים של האפליקציה, הקבצים שלי, צרו קישור ל-/library עם אחד משני פרמטרי שאילתה:

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

העלאה דרך עוזר AI

שרת ה-MCP מציע שלוש דרכים להעלות, וכל אחת מהן קיימת לתמונות, לאודיו ולווידאו. כולן דורשות את ההרשאה assets:write.