היקף ה-API הציבורי

כלל תכנון

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

• קראו את חוזה OpenAPI v1 הציבורי המסונן.

גבולות API v1 הציבורי כיום

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

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

לאחר אישור בטא, שלחו Authorization: Bearer <token> או X-Vietls-API-Key: <token>.

שמרו את X-Request-ID ואת requestId מהתשובה לצורך בירור תקלות. הם מזהים את הבקשה ואינם מחליפים את idempotencyKey של הפעולה.

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

• GET /api/public/v1/capabilities — גלו את הפעולות הזמינות דרך נקודת הקצה הציבורית לקריאה בלבד.
• POST /api/public/v1/quotes — בקשו תצוגת עלות מקדימה שאינה צורכת קרדיטים ואינה יוצרת משימה.

  {
    "workflowId": "prproj.subtitle.extract",
    "units": 1
  }

• POST /api/public/v1/jobs — צרו משימת בדיקה דטרמיניסטית ללא חיוב עם מזהה הצעת העלות שהוחזר, מפתח מניעת כפילויות, קבלה מפורשת של ההצעה ואישור משתמש. מזהה התוצאה הוא job_preview_*.

  {
    "workflowId": "prproj.subtitle.extract",
    "quoteId": "quote_preview_01234567",
    "idempotencyKey": "example-job-001",
    "confirmation": {
      "quoteAccepted": true,
      "userConfirmed": true
    }
  }

• GET /api/public/v1/jobs/{jobId} — תשאלו את המזהה שהוחזר job_preview_* וטפלו במצב completed_preview עם תוצרים ריקים.
• GET /api/public/v1/jobs/{jobId}/artifacts — רשימת artifacts ריקה היא תוצאת הסיום הצפויה של משימת בדיקה.
• GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — בקשו כתובת הורדה רק לאחר שמשימות אמיתיות שהושלמו מספקות תוצרים. תוצרי בדיקה מחזירים PUBLIC_API_ARTIFACT_NOT_FOUND.
• GET /api/public/v1/usage — בדקו שאין חיוב: השימוש בבדיקה מציג אפס קרדיטים משוריינים ואפס קרדיטים שנוצלו.
• POST /api/public/v1/billing/simulations — בדקו scenario: "success" ו-scenario: "provider_failure" כדי לאמת שריון, חיוב סופי ושחרור ללא שינוי בספר החשבונות. שלושת דגלי האישור חייבים להיות אמת.

  {
    "workflowId": "prproj.subtitle.extract",
    "quoteId": "quote_preview_01234567",
    "idempotencyKey": "example-simulation-001",
    "scenario": "success",
    "confirmation": {
      "quoteAccepted": true,
      "userConfirmed": true,
      "billingSimulationAccepted": true
    }
  }

• POST /api/public/v1/checkout/handoffs — בדקו את ההפניה לתשלום לאחר ששלושת אישורי המשתמש הוגדרו כאמת. התצוגה המקדימה מחזירה checkoutUrl: null, אינה גובה כסף ואינה יוצרת הפעלה אצל הספק או מנוי.

  {
    "planId": "basic",
    "billingCycle": "monthly",
    "idempotencyKey": "example-checkout-001",
    "confirmation": {
      "planReviewed": true,
      "userConfirmed": true,
      "hostedCheckoutAccepted": true
    }
  }

פעולות ציבוריות מתוכננות

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

עבודות עריכה לאוטומציה

• prproj.subtitle.extract — חילוץ כתוביות מ-PRPROJ

  כלי האתר זמין · אינטגרציית בטא ל-API/MCP בהכנה

  בדקו כתוביות וטקסט בגרפיקה בכלי האתר ובקשו גישת מפתחים לצורך אוטומציה.

• prproj.xml.inspect — מסירת XML ותיקון PRPROJ

  כלי האתר זמין · ממשק משימות ציבורי מתוכנן

  השתמשו בממיר להכנת מסירת XML, בדיקת סמני גרסה, תיקון נתיבים ואימות בתוכנה המקבלת.

• subtitle.translate — תרגום כתוביות

  זמין באפליקציה · ממשק הצעות מחיר ומשימות מתוכנן

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

• tts.standard.generate — המרת טקסט לדיבור רגילה

  חיבור לספק מנוהל בתהליך פריסה

  לפני פתיחת יצירה בתשלום דרך API או MCP נבדקים הצעת מחיר, שריון, ביצוע ואישור חיוב או שחרור.

• youtube.transcript.fetch — קליטת תמלול ומדיה מ-YouTube

  זמין באפליקציה · הכנת אוטומציה עם אימות זכויות

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

מודל שגיאות

תשובות הבטא הנוכחיות כוללות את קודי השגיאה הבאים:

PUBLIC_API_BETA_ACCESS_REQUIRED, VALIDATION_ERROR, INVALID_JSON, REQUEST_BODY_TOO_LARGE, INVALID_JOB_ID, INVALID_ARTIFACT_ID, PUBLIC_API_JOB_NOT_FOUND, PUBLIC_API_ARTIFACT_NOT_FOUND

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

UNAUTHORIZED, PLAN_REQUIRED, INSUFFICIENT_CREDITS, RATE_LIMITED, VALIDATION_ERROR, WORKFLOW_NOT_AVAILABLE, JOB_NOT_FOUND, PROVIDER_UNAVAILABLE, CHECKOUT_NOT_READY