# PPT জেনারেশন এবং এক্সপোর্ট

একটি প্রেজেন্টেশন তৈরি করুন, এর অগ্রগতি পোল করুন, একটি PPTX এক্সপোর্ট করুন এবং এর লাইফটাইম পরিচালনা করুন।

Asynchronously একটি presentation generate করুন, তারপর একটি PPTX file export করুন। Generation এবং export ধাপ আলাদা রাখুন: তৈরি করা task এখনও finished file নয়।

সব example-ই [overview](https://openapi.felo.ai/bn/docs/data-api/guides/felo-overview.md) থেকে `FELO_API_KEY` ব্যবহার করে। Call-গুলো **platform balance** ব্যবহার করে, Felo Pro credits নয়। Response example-গুলো illustrative; live content এবং optional field ভিন্ন হতে পারে।

## কর্মপ্রবাহ এবং পরিচায়কসমূহ

1. একটি generation task তৈরি করুন; `task_id`, `ppt_business_id` এবং `expires_at` সংরক্ষণ করুন।
2. `task_id` ব্যবহার করে generation status poll করুন।
3. `task_id` ব্যবহার করে generation result পড়ুন।
4. `ppt_business_id` ব্যবহার করে PPTX export শুরু করুন।
5. Export status poll করুন এবং completed file download করুন।
6. চাইলে presentation আগে থেকেই delete করুন।

Route placeholder-এ `{business_id}` বলতে ফেরত আসা **`ppt_business_id`** বোঝায়, `task_id`, `resource_id` বা `livedoc_short_id` নয়। পুরো workflow-এ একই API account ব্যবহার করুন। Example-এ থাকা ID-গুলো placeholder।

## 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` | স্ট্রিং অ্যারে | না | সর্বোচ্চ 100টি UUID সম্পদ পরিচায়ক; একই প্রেক্ষাপট প্রবেশাধিকার পরীক্ষার অধীন |

প্রথম integration-এর জন্য context এবং configuration field বাদ দিন। `/v2` দিয়ে তৈরি context এখানে স্বয়ংক্রিয়ভাবে পুনর্ব্যবহারের জন্য eligible নয়।

```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 root-এ identifier ফেরত দেয়:

```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`-এর মতো অতিরিক্ত identifier থাকতে পারে। Successful create response মানে task গৃহীত হয়েছে, generation সম্পূর্ণ হয়েছে—এমন নয়। Requested slide count একটি instruction; billing প্রকৃত generated page count ব্যবহার করে।

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

### SSE দিয়ে তৈরি হওয়ার ঘটনাসমূহ পড়ুন

যদি creation একটি `stream_key` ফেরত দেয়, একই account-এর একটি API Key দিয়ে সঙ্গে সঙ্গে connect করুন। যদি stream key না ফেরত দেয়, তবে নিচের status এবং result query ব্যবহার করুন।

```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 event পড়ুন, এর outer JSON decode করুন, তারপর `content` process করুন। একটি `answer` application event `data.text`-এ text বহন করে; `finished` stream-এ generation completion নির্দেশ করে। এছাড়াও upstream `done`, `[DONE]`, এবং `error` signal handle করুন। Completion signal ছাড়া connection বন্ধ হলে, task status query করুন।

[SuperAgent SSE](https://openapi.felo.ai/bn/docs/api-reference/superagent.md#2-sse)-এ থাকা parsing rules এবং client example ব্যবহার করুন, তবে এই section-এর `/api/v1/data/conversations/stream/{stream_key}` URL সহ। Stream শেষ হওয়ার পরে task result পড়ুন; PPTX export আলাদা ধাপই থাকে। এই endpoint `/api/v1/data/chat`-এ `stream: true` সক্রিয় করে না।

## 2. তৈরির অবস্থা অনুসন্ধান করুন

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

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

Response-এ root `status` string থাকে, যেমন `RUNNING` বা `COMPLETED`। সীমাবদ্ধ interval (উদাহরণস্বরূপ, 2–5 second) এবং deadline সহ poll করুন। Completion-এর পরে result-এ যান; success ধরে না নিয়ে failure এবং unexpected status handle করুন। Polling deadline task cancel করে না।

```json
{"status":"COMPLETED"}
```

## 3. তৈরি হওয়ার ফলাফল পড়ুন

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

এটি একটি **POST**, এবং কোনো JSON body প্রয়োজন নেই।

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

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

`history_data` ব্যবহার করার আগে `task_status` পড়ুন। History payload task অনুযায়ী ভিন্ন হতে পারে এবং null হতে পারে। `ai_page_html` এবং `thread_short_id` optional। এই response নিশ্চিত PPTX download URL নয়; এরপর export ব্যবহার করুন।

## 4. PPTX রপ্তানি শুরু করুন

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

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

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

Export করার আগে generation সম্পূর্ণ হওয়া আবশ্যক। একই export চলাকালীন POST পুনরাবৃত্তি করলে তা পুনর্ব্যবহৃত হয়। Completion-এর পরে আরেকটি export শুরু করলে নতুন export তৈরি হয় এবং আরেকটি charge লাগতে পারে। Polling এবং download link refresh করার জন্য GET ব্যবহার করুন।

## 5. রপ্তানি অনুসন্ধান করুন এবং ডাউনলোড করুন

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

```bash
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` | নতুন রপ্তানি জমা দেওয়ার আগে ত্রুটি এবং কার্য অবস্থাটি পরীক্ষা করুন |

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

Example URL illustrative। Response থেকে পাওয়া প্রকৃত signed URL ব্যবহার করুন। এটি **30 minutes**-এর জন্য বৈধ; presentation উপলভ্য থাকা পর্যন্ত GET export status নতুন link ফেরত দিতে পারে। এর lifetime-এর মধ্যে file save করুন। File download host-এ আপনার Felo API key পাঠাবেন না।

## 6. উপস্থাপনাটি মুছুন

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

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

Success হলে **HTTP 204 with no body** ফেরত আসে। এটিকে JSON হিসেবে parse করবেন না। Generation চলাকালীন deletion 409 ফেরত দেয়।

## জীবনকাল, মালিকানা এবং বিলিং

- Presentation-গুলো **creation-এর সাত দিন পরে** মেয়াদোত্তীর্ণ হয়। Query এবং export এই সময়সীমা বাড়ায় না। Presentation `expires_at` এবং signed download URL `expires_at` ভিন্ন lifetime বর্ণনা করে।
- কেবল creating API account-ই তার task এবং presentation access করতে পারে। Missing বা inaccessible resource 404 ফেরত দিতে পারে; expired বা deleted resource 410, অথবা cleanup-এর পরে 404 ফেরত দিতে পারে।
- Generation প্রতি generated page (`ppt.generate`) অনুযায়ী বিল হয়। Page pricing-এ creation দশ পেজের মূল্য রিজার্ভ করে, তারপর প্রকৃত successful output অনুযায়ী চূড়ান্ত হিসাব করে এবং অব্যবহৃত reservation ছেড়ে দেয়। Prompt কম page চাইলে-ও reservation-এর জন্য আপনার account-এ যথেষ্ট available balance থাকতে হবে।
- Export-এর আলাদা request price (`ppt.export`) আছে। Status query, result query, export-status query এবং deletion নতুন charge তৈরি করে না।
- Timeout-এর পরে আরেকটি presentation তৈরি না করে saved task query করুন। [Billing and Errors](https://openapi.felo.ai/bn/docs/data-api/guides/felo-billing.md) দেখুন।