Felo APIs

PPT Task API

کارهای تولید PPT بسازید، قالب‌ها را فهرست کنید و endpointهای مشترک کارها را بررسی کنید.

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

استفاده با عامل‌های هوش مصنوعی

برای ساخت اسلاید از یک عامل، بسته کامل felo-ai را نصب کنید، نه یک زیرمجموعه ثابت از Skillها. نصب‌کننده آن به‌صورت پویا هر پوشه بسته شامل SKILL.md را کشف می‌کند، از جمله PPT Skill و افزوده‌های آینده. همه Skillهای کشف‌شده را در پوشه بومی عامل خود نصب کنید: ~/.codex/skills مربوط به Codex، ~/.claude/skills مربوط به Claude Code، ~/.agents/skills مربوط به OpenClaw یا ~/.hermes/skills مربوط به Hermes Agent. برای پیکربندی کلید 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	شناسه تم؛ هنگام ساخت PPT از آن به‌عنوان `ai_theme_id` استفاده کنید
`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	بله	اعلان (prompt) درخواست تولید PPT
`livedoc_short_id`	string	خیر	شناسه کوتاه LiveDoc موجود برای اتصال به نشست PPT. اگر حذف شود، LiveDoc تازه‌ای به‌طور خودکار ساخته می‌شود.
`resource_ids`	آرایه‌ای از رشته‌ها	خیر	فهرست شناسه منابع 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 '{}'

هر 2–5 ثانیه GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export را با همان Bearer کلید API پیگیری کنید. صاحب کلید API باید مالک PPT باشد. هر دو endpoint مقدار data.status را برمی‌گردانند: NOT_STARTED، PROCESSING، COMPLETED یا FAILED. فقط COMPLETED مقدارهای download_url و expires_at را شامل می‌شود.

URL امضاشده دانلود 30 دقیقه پس از صدور منقضی می‌شود. برای URL تازه دوباره 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	فراخوانی پایین‌دستی استعلام وضعیت وظیفه شکست خورد