تولید و خروجی PPT

ارائه‌دهنده: Felo · پرداخت با موجودی پلتفرم

احراز هویت و راه‌اندازی صورتحساب و خطاها

یک ارائه را به‌صورت غیرهمزمان تولید کنید، سپس یک فایل PPTX خروجی بگیرید. مراحل تولید و خروجی را جدا نگه دارید: یک وظیفه ایجادشده هنوز یک فایل نهایی نیست.

تمام نمونه‌ها از FELO_API_KEY از نمای کلی استفاده می‌کنند. تماس‌ها از موجودی پلتفرم استفاده می‌کنند، نه اعتبارات Felo Pro. نمونه‌های پاسخ صرفاً نمایشی هستند؛ محتوای زنده و فیلدهای اختیاری متفاوت‌اند.

گردش‌کار و شناسه‌ها

یک وظیفه تولید ایجاد کنید؛ task_id، ppt_business_id و expires_at را ذخیره کنید.
با استفاده از task_id وضعیت تولید را بررسی کنید.
نتایج تولید را با استفاده از task_id بخوانید.
با استفاده از ppt_business_id خروجی PPTX را آغاز کنید.
وضعیت خروجی را بررسی کنید و فایل تکمیل‌شده را دانلود کنید.
در صورت نیاز، ارائه را زودتر حذف کنید.

در جای‌نگهدارهای مسیر، {business_id} به `ppt_business_id` بازگردانده‌شده اشاره دارد، نه task_id، resource_id یا livedoc_short_id. برای کل گردش‌کار از همان حساب API استفاده کنید. شناسه‌های موجود در نمونه‌ها صرفاً جای‌نگهدار هستند.

1. ایجاد ارائه

POST /api/v1/data/ppts

فیلد	نوع	الزامی	معنا
`query`	string	بله	دستورهای تولید، 1 تا 25,000 نویسه
`stream_protocol`	string	خیر	پیش‌فرض `message_center_v1`; معمولاً بدون تغییر بگذارید
`ppt_config`	object	خیر	پیکربندی اختیاری؛ پیاده‌سازی فعلی `ai_theme_id` را می‌خواند
`livedoc_short_id`	string	خیر	شناسه زمینه موجود، تا 100 نویسه؛ باید بررسی‌های بومی مالکیت API و انقضا را بگذراند
`resource_ids`	آرایه string	خیر	تا 100 شناسه منبع UUID؛ مشمول همان بررسی‌های دسترسی به زمینه

برای اولین یکپارچه‌سازی، فیلدهای زمینه و پیکربندی را حذف کنید. زمینه‌ای که از طریق /v2 ایجاد شده باشد، به‌طور خودکار برای استفاده مجدد در اینجا واجد شرایط نیست.

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Create a 5-slide introduction to retrieval augmented generation for software developers."}'

HTTP 200 شناسه‌ها را در ریشه برمی‌گرداند:

{
  "task_id":"example-task-id",
  "ppt_business_id":"example-ppt-id",
  "livedoc_short_id":"example-livedoc-id",
  "expires_at":"2026-11-13T00:00:00Z"
}

شناسه‌های دیگری مانند resource_id، stream_key و thread_short_id نیز ممکن است حاضر باشند. یک پاسخ موفق ایجاد به این معناست که وظیفه پذیرفته شده است، نه اینکه تولید کامل شده باشد. تعداد اسلاید درخواستی یک دستور است؛ صورتحساب بر اساس تعداد صفحات واقعاً تولیدشده انجام می‌شود.

TASK_ID="example-task-id"
PPT_ID="example-ppt-id"

خواندن رویدادهای تولید با SSE

اگر ایجاد یک stream_key برگرداند، بلافاصله با یک API Key متعلق به همان حساب متصل شوید. اگر هیچ stream key بازگردانده نشد، از پرس‌وجوهای وضعیت و نتیجه در پایین استفاده کنید.

curl -N 'https://openapi.felo.ai/api/v1/data/conversations/stream/YOUR_STREAM_KEY?format=structured' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

پارامتر پرس‌وجو	معنا
`format`	`raw` (پیش‌فرض) رشته `content` را حفظ می‌کند؛ `structured` JSON معتبر را به یک شیء یا آرایه رمزگشایی می‌کند
`offset`	موقعیت ادامه بالادستی اختیاری برای اتصال مجدد؛ آن را از شمارش رویداد محلی خود استنباط نکنید

هر رویداد کامل SSE را بخوانید، JSON بیرونی آن را رمزگشایی کنید، سپس content را پردازش کنید. یک رویداد کاربردی answer متن را در data.text حمل می‌کند؛ finished پایان تولید را در جریان نشان می‌دهد. همچنین سیگنال‌های بالادستی done، [DONE] و error را مدیریت کنید. اگر اتصال بدون سیگنال تکمیل بسته شد، وضعیت وظیفه را بررسی کنید.

از قواعد تجزیه و نمونه کلاینت در SuperAgent SSE، با نشانی /api/v1/data/conversations/stream/{stream_key} این بخش استفاده کنید. نتیجه وظیفه را پس از پایان جریان بخوانید؛ خروجی PPTX همچنان یک مرحله جداگانه باقی می‌ماند. این پایانه stream: true را روی /api/v1/data/chat فعال نمی‌کند.

2. بررسی دوره‌ای وضعیت تولید

GET /api/v1/data/tasks/{task_id}/status

curl -sS --request GET "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/status" \
  -H "Authorization: Bearer $FELO_API_KEY"

پاسخ یک رشته status در ریشه دارد، برای مثال RUNNING یا COMPLETED. با یک بازه محدود (مثلاً 2 تا 5 ثانیه) و یک مهلت نهایی پرس‌وجو کنید. پس از تکمیل به نتایج ادامه دهید؛ شکست و وضعیت‌های غیرمنتظره را بدون فرض موفقیت مدیریت کنید. یک مهلت بررسی دوره‌ای، وظیفه را لغو نمی‌کند.

{"status":"COMPLETED"}

3. خواندن نتایج تولید

POST /api/v1/data/tasks/{task_id}/historical

این یک POST است و به هیچ بدنه JSONی نیاز ندارد.

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/historical" \
  -H "Authorization: Bearer $FELO_API_KEY"

{
  "task_id":"example-task-id",
  "task_status":"COMPLETED",
  "history_data":{},
  "error_message":null
}

پیش از استفاده از history_data، task_status را بخوانید. بار تاریخچه می‌تواند بسته به وظیفه متفاوت باشد و ممکن است null باشد. ai_page_html و thread_short_id اختیاری هستند. این پاسخ یک URL دانلود تضمینی PPTX نیست؛ در مرحله بعد از خروجی استفاده کنید.

4. آغاز خروجی PPTX

POST /api/v1/data/ppts/{business_id}/export

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"

{"status":"PROCESSING","download_url":null,"expires_at":null}

تولید باید پیش از خروجی کامل شده باشد. تکرار POST در حالی که همان خروجی در حال اجرا است، همان مورد را بازاستفاده می‌کند. آغاز یک خروجی دیگر پس از تکمیل، یک خروجی جدید ایجاد می‌کند و می‌تواند هزینه دیگری در پی داشته باشد. برای بررسی دوره‌ای و تازه‌سازی پیوند دانلود از GET استفاده کنید.

5. بررسی دوره‌ای خروجی و دانلود

GET /api/v1/data/ppts/{business_id}/export

curl -sS --request GET "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"

وضعیت	اقدام بعدی
`NOT_STARTED`	خروجی را یک‌بار ارسال کنید
`PROCESSING`	صبر کنید، سپس دوباره GET را بررسی کنید
`COMPLETED`	`download_url` را بخوانید و فایل را دانلود کنید
`FAILED`	پیش از ارسال یک خروجی جدید، خطا و وضعیت وظیفه را بررسی کنید

{
  "status":"COMPLETED",
  "download_url":"https://example.com/presentation.pptx?signature=example",
  "expires_at":"2026-11-06T00:30:00Z"
}

نشانی نمونه صرفاً نمایشی است. از URL امضاشده واقعیِ موجود در پاسخ استفاده کنید. این URL به مدت 30 دقیقه معتبر است؛ بررسی وضعیت خروجی GET می‌تواند پیوند تازه‌ای بازگرداند در حالی که ارائه همچنان در دسترس است. فایل را در طول عمر آن ذخیره کنید. کلید API Felo خود را برای میزبان دانلود فایل ارسال نکنید.

6. حذف ارائه

DELETE /api/v1/data/ppts/{business_id}

curl -sS --request DELETE "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID" \
  -H "Authorization: Bearer $FELO_API_KEY"

موفقیت HTTP 204 بدون بدنه برمی‌گرداند. آن را به‌صورت JSON تجزیه نکنید. حذف در حالی که تولید در حال اجرا است، 409 برمی‌گرداند.

چرخه عمر، مالکیت و صورتحساب

ارائه‌ها هفت روز پس از ایجاد منقضی می‌شوند. پرس‌وجوها و خروجی‌ها این دوره را تمدید نمی‌کنند. expires_at ارائه و expires_at URL امضاشده دانلود، دو چرخه عمر متفاوت را توصیف می‌کنند.
فقط حساب API ایجادکننده می‌تواند به وظایف و ارائه‌های خود دسترسی داشته باشد. یک منبع مفقود یا غیرقابل‌دسترسی می‌تواند 404 برگرداند؛ یک منبع منقضی‌شده یا حذف‌شده می‌تواند 410 یا پس از پاک‌سازی 404 برگرداند.
تولید بر اساس هر صفحه تولیدشده (ppt.generate) صورتحساب می‌شود. در قیمت‌گذاری صفحه‌ای، ایجاد قیمت ده صفحه را رزرو می‌کند، سپس خروجی موفق واقعی را تسویه می‌کند و رزرو استفاده‌نشده را آزاد می‌سازد. حساب شما حتی اگر پرسش صفحات کمتری را درخواست کند، باید موجودی در دسترس کافی برای رزرو داشته باشد.
خروجی یک قیمت درخواست جداگانه دارد (ppt.export). پرس‌وجوهای وضعیت، پرس‌وجوهای نتیجه، پرس‌وجوهای وضعیت خروجی و حذف هیچ هزینه جدیدی ایجاد نمی‌کنند.
پس از یک زمان‌اِتمام، به‌جای ایجاد یک ارائه دیگر، وظیفه ذخیره‌شده را پرس‌وجو کنید. به صورتحساب و خطاها مراجعه کنید.

به کمک نیاز دارید؟

برای پرسش‌های مربوط به API، صورت‌حساب و حساب کاربری با پشتیبانی در تماس باشید.
با توسعه‌دهندگان Felo در Discord گفت‌وگو کنید.
تاریخچه تغییرات ما را ببینید.
به قیمت‌گذاری حجمی یا کمک در خرید نیاز دارید؟ تماس با فروش.
با LLM می‌سازید؟ llms.txt را بخوانید.