בקשות

בקשה היא קריאה אחת למודל אחד. יש לה מזהה (req_…), סטטוס, עלות בקרדיטי API (1000 = 1 USD), וכאשר היא מסתיימת בהצלחה — את הקבצים שנוצרו. אותו אובייקט מוחזר מכל נקודת קצה למטה, עבור כל מודל.

מציאת מודל#

הקטלוג של כל 1,496 המודלים הוא JSON ציבורי (אין צורך במפתח):

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

בכל שורה יש id, name, lab, category, family, summary, tags, output_kind, docs_url ואובייקט price (ראו תמחור). GET https://api.doitong.com/v1/models/{model_id} מוסיף את סכימת ה-JSON המלאה של הקלט והפלט, את שמות הפרמטרים הקנוניים, את כללי המחיר ודוגמה לקלט. category או mode לא מוכרים מחזירים 400 invalid_parameter.

הרצת מודל#

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

• גוף הבקשה הוא קלט המודל, כאובייקט JSON. בכל עמוד מודל מפורטים הפרמטרים שלו.
• הקלט נבדק לפני כל חיוב. קלט לא חוקי מחזיר 422 invalid_input עם ה-param הבעייתי, ואינו עולה דבר.
• ?wait=N (עד 20 שניות) מחזיק את הקריאה עד שהבקשה מסתיימת או עד שהזמן פג.
• ?webhook_url=https://… שולח POST חתום לכתובת הזו כשהבקשה מסתיימת (ראו webhook).
• ?storage=permanent או ?storage=temporary בוחר כמה זמן קובצי הפלט יישמרו; בלעדיו חלה הגדרת החשבון (ראו היכן הקבצים נשמרים).

התגובה היא 202 Accepted כל עוד הבקשה עדיין בעבודה, ו-200 OK כשהיא הסתיימה במהלך זמן ההמתנה (או כאשר זו הפעלה חוזרת, ראו להלן). הכותרות Location ו-Doitong-Request-Id מכילות את כתובת הבקשה ואת המזהה שלה.

סטטוסים#

בקשה שנמשכת מעבר למגבלת הזמן שלה נכשלת עם הקוד timeout, והחיוב מוחזר: 15 דקות לתמונות, 60 דקות לווידאו, 30 דקות לאודיו ולכל השאר.

אובייקט הבקשה#

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• outputs זהה לכל המודלים: רשומה אחת לכל קובץ שנוצר, עם type (image, video, audio, file או 3d), כתובת url באחסון שלנו, content_type וכאשר ידועים גם file_size, width, height, duration.
• output הוא אובייקט התוצאה של המודל עצמו (השדות שלו מפורטים בכל עמוד מודל), עם אותן כתובות URL.
• storage מציין כיצד הקבצים נשמרים: mode (permanent או temporary), מספר ה-bytes שנשמרו, expires_at (מתי קובץ זמני יימחק, null עבור קבצים קבועים) ו-expired (true לאחר שהקבצים נעלמו).
• cost.credits הוא מחיר הקריאה בקרדיטי API (cost.usd ב-USD), cost.charged הוא הסכום שנוכה מיתרת ה-API, ו-cost.refunded הוא הסכום שהוחזר. עבור מודל metered, cost.credits הוא המקסימום שהוחזק בתחילת ההרצה (cost.held); לאחר שההרצה מצליחה, cost.settled מציין את עלות השימוש, ויתרת המקסימום נמצאת ב-cost.refunded (ראו חיוב לפי שימוש).
• כאשר בקשה נכשלת, error הוא { "type": …, "code": …, "message": … }.

קריאת בקשה#

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• ?wait=N (עד 20 שניות) מבצע long-polling: הקריאה חוזרת מיד כשהבקשה סופית, או לאחר N שניות עם המצב הנוכחי. לולאה על פרמטר זה היא הדרך הפשוטה ביותר להמתין לתוצאה.
• ?logs=1 מוסיף את שורות יומן ההתקדמות של המודל (50 האחרונות) בתור logs.

אפשר לקרוא רק בקשות של החשבון שלך; כל מזהה אחר מחזיר 404 request_not_found.

הצגת בקשות#

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

מהחדשה לישנה. limit הוא 1 עד 100 (ברירת מחדל 20), ו-status ו-model מסננים את התוצאות. התגובה היא { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; העבר cursor=<next_cursor> כדי לקבל את העמוד הבא.

ביטול בקשה#

curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• בוטלה לפני שהמודל התחיל: הסטטוס הופך ל-canceled, קרדיטי ה-API מוחזרים ומתקבלת תשובת 200.
• כבר מתבצעת יצירה: הביטול מועבר ומתקבלת תשובת 202 עם "cancel_requested": true. אם המודל יסיים בכל זאת, הבקשה תצליח כרגיל ותחויב.
• כבר סופית: 409 not_cancelable (בקשה שכבר במצב canceled פשוט מחזירה 200).

מחיקת קובצי בקשה#

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

מוחק מיד את העותקים שלנו של קובצי הפלט של הבקשה ומפסיק את חיוב האחסון שלהם. התגובה היא אובייקט הבקשה עם storage.expired: true; כתובות ה-URL נשארות ברשומה אך אינן פועלות עוד. קריאה חוזרת אינה משנה דבר (200). לבקשה שעדיין נמצאת ב-queued או ב-running אין עדיין קבצים: 409 request_active. נדרש models:run.

אידמפוטנטיות: ניסיון חוזר ללא חיוב כפול#

רשתות נכשלות. כדי לנסות הרצה שוב בבטחה, שלח כותרת Idempotency-Key (כל מחרוזת באורך של עד 255 תווים, ייחודית לכל פעולה, לדוגמה מזהה ההזמנה שלך):

• אותו מפתח ואותו גוף כמו קודם: אובייקט הבקשה המקורי מוחזר (200, כותרת Idempotent-Replayed: true), ולא מתבצע חיוב נוסף.
• אותו מפתח וגוף לאחר הרצה שנכשלה לפני שהגיעה למודל (upstream_error או internal_error בעת השליחה, insufficient_credits, budget_exceeded, too_many_inflight): לא נוצר דבר ולא מתבצע חיוב, ולכן ניסיון חוזר מריץ שוב את המודל במקום להחזיר את הכשל.
• אותו מפתח עם גוף שונה: 409 idempotency_mismatch.
• המפתחות משויכים למפתח ה-API ששלח אותם.

היכן הקבצים נשמרים#

כל קובץ פלט מועתק לאחסון שלנו לפני שהבקשה מסומנת כ-succeeded, ולכן כתובות ה-URL ב-outputs נמצאות בשרתים שלנו ואפשר לקשר אליהן ישירות. כמה זמן הן יישארו — זו בחירתך:

• הגדרת החשבון קובעת עבור בקשות חדשות: המתג "שמירת קבצים לצמיתות" ב-לוח הבקרה, או PATCH https://api.doitong.com/v1/account/storage עם {"mode": "temporary"}. GET https://api.doitong.com/v1/account מציג אותה תחת storage, עם מספר הבתים שנשמרים וההערכה החודשית.
• ?storage=permanent|temporary בהרצה (הארגומנט storage של כלי run ב-MCP) עוקף אותה עבור ההרצה הזו.
• שינוי ההגדרה לעולם אינו משפיע על קבצים שכבר ברשותך; מחק אותם באמצעות DELETE /requests/{id}/files.
• כאשר יתרת ה-API אינה יכולה לשלם על האחסון, לא מתבצע חיוב ונשלחת אליך הודעת דוא״ל: טען את היתרה בתוך 30 ימים, אחרת הקבצים הנשמרים יהפכו לזמניים ויימחקו 7 ימים לאחר מכן.

במקרה הנדיר שבו העותק שלנו נכשל, הרשומה כוללת "stored": false וה-URL הוא המקורי וקצר-הטווח: הורד אותו בהקדם.