# ایجاد ارائه Felo

POST /api/v1/data/ppts

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

تمام نمونه‌ها از `FELO_API_KEY` از [نمای کلی](https://openapi.felo.ai/fa/docs/data-api/guides/felo-overview.md) استفاده می‌کنند. تماس‌ها از **موجودی پلتفرم** استفاده می‌کنند، نه اعتبارات Felo Pro. نمونه‌های پاسخ صرفاً نمایشی هستند؛ محتوای زنده و فیلدهای اختیاری متفاوت‌اند.





## 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` ایجاد شده باشد، به‌طور خودکار برای استفاده مجدد در اینجا واجد شرایط نیست.

```bash
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 شناسه‌ها را در ریشه برمی‌گرداند:

```json
{
  "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` نیز ممکن است حاضر باشند. یک پاسخ موفق ایجاد به این معناست که وظیفه پذیرفته شده است، نه اینکه تولید کامل شده باشد. تعداد اسلاید درخواستی یک دستور است؛ صورتحساب بر اساس تعداد صفحات واقعاً تولیدشده انجام می‌شود.

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

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

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

```bash
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](https://openapi.felo.ai/fa/docs/api-reference/superagent.md#2-sse)، با نشانی `/api/v1/data/conversations/stream/{stream_key}` این بخش استفاده کنید. نتیجه وظیفه را پس از پایان جریان بخوانید؛ خروجی PPTX همچنان یک مرحله جداگانه باقی می‌ماند. این پایانه `stream: true` را روی `/api/v1/data/chat` فعال نمی‌کند.



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

- ارائه‌ها **هفت روز پس از ایجاد** منقضی می‌شوند. پرس‌وجوها و خروجی‌ها این دوره را تمدید نمی‌کنند. `expires_at` ارائه و `expires_at` URL امضاشده دانلود، دو چرخه عمر متفاوت را توصیف می‌کنند.
- فقط حساب API ایجادکننده می‌تواند به وظایف و ارائه‌های خود دسترسی داشته باشد. یک منبع مفقود یا غیرقابل‌دسترسی می‌تواند 404 برگرداند؛ یک منبع منقضی‌شده یا حذف‌شده می‌تواند 410 یا پس از پاک‌سازی 404 برگرداند.
- تولید بر اساس هر صفحه تولیدشده (`ppt.generate`) صورتحساب می‌شود. در قیمت‌گذاری صفحه‌ای، ایجاد قیمت ده صفحه را رزرو می‌کند، سپس خروجی موفق واقعی را تسویه می‌کند و رزرو استفاده‌نشده را آزاد می‌سازد. حساب شما حتی اگر پرسش صفحات کمتری را درخواست کند، باید موجودی در دسترس کافی برای رزرو داشته باشد.
- خروجی یک قیمت درخواست جداگانه دارد (`ppt.export`). پرس‌وجوهای وضعیت، پرس‌وجوهای نتیجه، پرس‌وجوهای وضعیت خروجی و حذف هیچ هزینه جدیدی ایجاد نمی‌کنند.
- پس از یک زمان‌اِتمام، به‌جای ایجاد یک ارائه دیگر، وظیفه ذخیره‌شده را پرس‌وجو کنید. به [صورتحساب و خطاها](https://openapi.felo.ai/fa/docs/data-api/guides/felo-billing.md) مراجعه کنید.