Felo APIs

PPT Task API

צרו משימות יצירת PPT, הציגו ערכות נושא ובדקו endpoints משותפים של משימות.

POST/v2/ppts

אימות

Bearer API key

סוג תוכן

application/json

הערות תעריף

ייתכנו מגבלות ספציפיות ל-endpoint.

LiveDoc API Landing Page Task API

ה-PPT Task API מספק יכולות יצירת PPT אסינכרוניות. אפשר ליצור משימה ואז לבדוק את מצב המשימה לפי task_id. אפשר גם לעיין בערכות הנושא הזמינות ל-PPT ולהחיל אותן בעת יצירת משימות.

זהו API אסינכרוני. לדפוס המשותף של שליחה, בדיקה חוזרת ואחזור, ראו משימות אסינכרוניות.

אימות

כל הבקשות דורשות מפתח API בכותרת Authorization:

Authorization: Bearer YOUR_API_KEY

שימוש עם סוכני AI

כדי ליצור שקופיות מתוך סוכן, התקינו את החבילה המלאה felo-ai ולא תת-קבוצה קבועה של Skills. המתקין שלה מגלה באופן דינמי כל תיקיית חבילה שמכילה SKILL.md, כולל ה-Skill של PPT ותוספות עתידיות. התקינו את כל ה-Skills שהתגלו בתיקייה הייעודית של הסוכן שלכם: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills או Hermes Agent ~/.hermes/skills. עקבו אחרי מדריך ההגדרה הידנית לסוכני AI לתצורת מפתח ה-API ולאימות הייחודיים לפלטפורמה.

1. List PPT Themes

שאלו ערכות נושא זמינות ל-PPT עם חלוקה לעמודים, חיפוש לפי מילת מפתח וסינון לפי שפה וסוג.

Endpoint

GET https://openapi.felo.ai/v2/ppt-themes

פרמטרי שאילתה

פרמטר	סוג	חובה	תיאור
`lang`	string	לא	קוד שפה לתוכן מתורגם (למשל `en`, `zh-Hans`). ברירת מחדל: `en`
`type`	string	לא	סינון לפי סוג ערכת נושא (למשל `default`, `custom`)
`keyword`	string	לא	מילת מפתח לחיפוש, מתאימה לכותרות ערכות הנושא
`page`	integer	לא	מספר עמוד, מתחיל מ-1. ברירת מחדל: `1`
`size`	integer	לא	גודל עמוד, עד 100. ברירת מחדל: `20`

דוגמה

curl -X GET 'https://openapi.felo.ai/v2/ppt-themes?lang=en&page=1&size=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

תגובת הצלחה (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 8,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": "43122897-0d3c-4c9e-ae19-20527ad36c04",
        "title": "Inspiration Themes",
        "subtitle": "AI-tailored visual solutions",
        "description": "Style and layout, both crafted by AI from your content in real time"
      }
    ]
  }
}

שדות תגובת ערכת הנושא

שדה	סוג	תיאור
`total`	integer	מספר ערכות הנושא הכולל שמתאים לסינון
`page`	integer	מספר העמוד הנוכחי
`size`	integer	גודל העמוד
`items`	array	רשימת אובייקטי ערכת נושא
`items[].id`	string	מזהה ערכת הנושא, השתמשו בו כ-`ai_theme_id` בעת יצירת PPT
`items[].title`	string	כותרת ערכת הנושא (מתורגמת)
`items[].subtitle`	string	כותרת משנה של ערכת הנושא (מתורגמת)
`items[].description`	string	תיאור ערכת הנושא (מתורגם)

2. יצירת משימת PPT

Endpoint

POST https://openapi.felo.ai/v2/ppts

כותרות הבקשה

כותרת	חובה	תיאור
`Authorization`	כן	מפתח ה-API שלכם בפורמט `Bearer YOUR_API_KEY`
`Content-Type`	כן	`application/json` או `multipart/form-data`

גוף הבקשה

פרמטר	סוג	חובה	תיאור
`query`	string	כן	פרומפט לבקשת יצירת PPT
`livedoc_short_id`	string	לא	מזהה מקוצר של LiveDoc קיים לשיוך לסשן ה-PPT. אם הוא מושמט, נוצר LiveDoc חדש אוטומטית.
`resource_ids`	array of strings	לא	רשימת מזהי משאבים של LiveDoc לשימוש כהקשר ליצירת ה-PPT
`ppt_config`	object	לא	אפשרויות תצורה ל-PPT
`ppt_config.ai_theme_id`	string	לא	מזהה ערכת נושא מה-endpoint של List PPT Themes

דוגמה

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Felo, 2 pages",
    "ppt_config": {
      "ai_theme_id": "02968979-a69f-42c4-b136-de02c40ab2d7"
    }
  }'

יצירה מקובץ שהועלה

השתמשו ב-multipart/form-data כדי להעלות קובץ אחד וליצור משימת PPT בבקשה אחת. הפלטפורמה מעלה את הקובץ תחילה כמשאב LiveDoc, ואז מעבירה את מזהה המשאב שלו למשימת ה-PPT.

חלק	סוג	חובה	תיאור
`query`	string	כן	פרומפט לבקשת יצירת PPT
`file`	file	כן	קובץ המקור המשמש כהקשר ל-PPT
`stream_protocol`	string	לא	פרוטוקול זרם; ברירת מחדל `message_center_v1`
`livedoc_short_id`	string	לא	LiveDoc קיים שיקבל את הקובץ. LiveDoc חדש נוצר כשהשדה מושמט.
`ppt_config`	JSON	לא	תצורת PPT באותו מבנה כמו גוף בקשת ה-JSON. שלחו את החלק הזה כ-`application/json`.

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=Create a 10-page presentation based on this report' \
  -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \
  -F '[email protected]'

התגובה משתמשת באותה סכימה כמו בקשת ה-JSON. ה-livedoc_short_id שמוחזר מזהה את ה-LiveDoc שמכיל את המשאב שהועלה.

תגובת הצלחה (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3",
    "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr",
    "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9"
  }
}

3. שאילת מצב המשימה

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/status

דוגמה

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

תגובת הצלחה (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "RUNNING"
  }
}

4. שאילת מידע היסטורי על המשימה

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/historical

דוגמה

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cb17e-9e23-3d40-4447-48a651249460/historical' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

תגובת RUNNING

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "RUNNING",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

תגובת COMPLETED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "COMPLETED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

תגובת COMPLETED (AI_PAGE)

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621",
    "task_status": "COMPLETED",
    "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ",
    "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ",
    "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ"
  }
}

תגובת FAILED / PENDING / EXPIRED / CANCELED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "FAILED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "error_message": "PPT generation failed",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

שדות התגובה ההיסטורית

שדה	סוג	תיאור
`task_id`	string	מזהה המשימה
`task_status`	string	מצב המשימה הנוכחי
`ppt_biz_id`	string	מזהה העסקי של ה-PPT (ממופה מהשדה `thread_short_id` בצד השרת)
`ppt_url`	string	כתובת ה-URL של ה-PPT, פורמט: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	קיים עבור `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; מחרוזת ריקה `""` כשהמערכת במורד הזרם אינה מספקת פרטי שגיאה
`ai_page_html`	string	קיים כשהמשימה רצה במצב AI_PAGE והמידע ההיסטורי במורד הזרם מחזיר כתובת URL של תוצאת HTML
`live_doc_short_id`	string	מזהה מקוצר של LiveDoc. עבור `COMPLETED` הוא מגיע מהשדה `live_doc_short_id` במורד הזרם; עבור מצבי כשל סופיים הוא מוחזר כשהוא זמין
`live_doc_url`	string	כתובת ה-URL של LiveDoc המתאימה ל-`live_doc_short_id`

ייצוא PPTX

לאחר שמשימת יצירת ה-PPT מגיעה ל-COMPLETED, שלחו ייצוא אסינכרוני באמצעות ppt_business_id מתגובת היצירה (או ppt_biz_id מהתגובה ההיסטורית):

curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

בדקו שוב ושוב את GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export עם אותו מפתח Bearer API בכל 2–5 שניות. בעל מפתח ה-API חייב להיות הבעלים של ה-PPT. שתי נקודות הקצה מחזירות data.status: NOT_STARTED, PROCESSING, COMPLETED או FAILED. רק COMPLETED כולל download_url ו-expires_at.

כתובת ההורדה החתומה פגה 30 דקות לאחר ההנפקה. קראו שוב ל-endpoint של GET כדי לקבל כתובת חדשה; פעולה זו אינה יוצרת מחדש את ה-PPTX. POST משתמש ב-application/json ומקבל {}. חזרה על POST בזמן שייצוא נמצא בעיבוד אינה מפעילה משימה נוספת; קריאה לו לאחר ההשלמה יוצרת מחדש את ה-PPTX ומחייבת בחיוב הקרדיטים הקיים של ייצוא PPT. קרדיטים לא מספיקים מחזירים HTTP 402. ייתכנו מגבלות קצב ייחודיות ל-endpoint; נסו שוב מאוחר יותר ב-HTTP 429. אפשר לשלוח שוב ייצוא שנכשל.

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "COMPLETED",
    "download_url": "https://example.com/presentation.pptx?signature=...",
    "expires_at": "2026-09-29T10:30:00Z"
  }
}

המלצת בדיקה חוזרת

השתמשו ב-task_id מתגובת היצירה ובדקו את המצב בכל 2-5 שניות עד שהמצב הופך למצב סופי.

דוגמאות למצבים נפוצים:

RUNNING: המשימה עדיין בעיבוד
COMPLETED: המשימה הושלמה בהצלחה
FAILED / PENDING / EXPIRED / CANCELED: המשימה הגיעה למצב סופי עם error_message; גם live_doc_url מוחזר כשהוא זמין

ערכי מצב לא מוכרים עשויים להופיע ככל שהמערכת במורד הזרם מתפתחת; התייחסו אליהם כלא-סופיים אלא אם צוין אחרת.

קודי שגיאה

קוד	סטטוס HTTP	תיאור
`UNAUTHORIZED`	401	מפתח ה-API לא חוקי או בוטל
`PPT_TASK_CREATE_FAILED`	502	הקריאה ליצירת המשימה במורד הזרם נכשלה
`PPT_TASK_QUERY_FAILED`	502	הקריאה לשאילת מצב המשימה במורד הזרם נכשלה