# PPT जनरेशन और निर्यात

एक प्रस्तुति बनाएँ, उसकी प्रगति poll करें, एक PPTX निर्यात करें और उसकी lifetime प्रबंधित करें।

एक प्रस्तुति को asynchronously generate करें, फिर एक PPTX file export करें। Generation और export steps को अलग रखें: created task अभी finished file नहीं होती।

सभी examples [overview](https://openapi.felo.ai/hi/docs/data-api/guides/felo-overview.md) से `FELO_API_KEY` का उपयोग करते हैं। Calls **platform balance** का उपयोग करती हैं, Felo Pro credits का नहीं। Response examples केवल illustrative हैं; live content और optional fields बदलते रहते हैं।

## कार्यप्रवाह और पहचानकर्ता

1. एक generation task बनाएँ; `task_id`, `ppt_business_id` और `expires_at` save करें।
2. `task_id` का उपयोग करके generation status poll करें।
3. `task_id` का उपयोग करके generation results पढ़ें।
4. `ppt_business_id` का उपयोग करके PPTX export शुरू करें।
5. Export status poll करें और completed file download करें।
6. वैकल्पिक रूप से प्रस्तुति को जल्दी delete करें।

Route placeholders में `{business_id}` का अर्थ लौटाया गया **`ppt_business_id`** है, `task_id`, `resource_id` या `livedoc_short_id` नहीं। पूरे workflow के लिए वही API account उपयोग करें। Examples में IDs placeholders हैं।

## 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 | नहीं | मौजूदा संदर्भ ID, अधिकतम 100 वर्ण; नेटिव API स्वामित्व और समाप्ति जाँचों को पास करना चाहिए |
| `resource_ids` | स्ट्रिंग सरणी | नहीं | अधिकतम 100 UUID संसाधन IDs; वही संदर्भ पहुँच जाँचें लागू हैं |

पहले integration के लिए, context और configuration fields को छोड़ दें। `/v2` के माध्यम से बना context यहाँ अपने-आप reuse के लिए 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 पर identifiers लौटाता है:

```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"
}
```

अतिरिक्त identifiers जैसे `resource_id`, `stream_key` और `thread_short_id` भी मौजूद हो सकते हैं। Successful create response का अर्थ है कि task स्वीकार कर ली गई, यह नहीं कि generation पूरी हो गई। Requested slide count केवल instruction है; billing actual 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 queries का उपयोग करें।

```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` | पुनःकनेक्शन के लिए वैकल्पिक अपस्ट्रीम पुनःआरंभ स्थिति; इसे अपनी स्थानीय घटना संख्या से अनुमान न लगाएँ |

हर complete SSE event पढ़ें, उसकी outer JSON decode करें, फिर `content` process करें। एक `answer` application event `data.text` में text रखता है; `finished` stream में generation completion का संकेत देता है। Upstream `done`, `[DONE]`, और `error` signals को भी handle करें। यदि completion signal के बिना connection बंद हो जाए, तो task status query करें।

[SuperAgent SSE](https://openapi.felo.ai/hi/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 अलग step ही रहती है। यह 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`। Bounded interval (उदाहरण के लिए, 2–5 seconds) और एक deadline के साथ poll करें। Completion के बाद results पर जाएँ; success मान लेने के बजाय failure और unexpected statuses को 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 guaranteed PPTX download URL नहीं है; अगला step 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 दोहराने से उसी का reuse होता है। 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 से actual signed URL का उपयोग करें। यह **30 minutes** के लिए valid है; जब तक प्रस्तुति उपलब्ध है, GET export status एक fresh link लौटा सकता है। File को उसकी lifetime के भीतर save करें। अपनी Felo API key को file download host पर न भेजें।

## 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 बिना body** के लौटता है। इसे JSON की तरह parse न करें। Generation चलते समय deletion पर 409 लौटता है।

## अवधि, स्वामित्व और बिलिंग

- प्रस्तुतियाँ **creation के सात दिन बाद** expire हो जाती हैं। Queries और exports इस अवधि को extend नहीं करते। Presentation `expires_at` और signed download URL `expires_at` अलग lifetimes का वर्णन करते हैं।
- केवल बनाने वाला API account ही अपनी tasks और presentations access कर सकता है। Missing या inaccessible resource पर 404 लौट सकता है; expired या deleted resource पर 410, या cleanup के बाद 404 लौट सकता है।
- Generation का बिल प्रति generated page (`ppt.generate`) लगता है। Page pricing के अंतर्गत, creation दस pages की कीमत reserve करती है, फिर actual successful output के अनुसार settlement करती है और unused reservation release करती है। यदि prompt में कम pages माँगे गए हों तब भी आपके account में reservation के लिए पर्याप्त available balance होना चाहिए।
- Export की अलग request price (`ppt.export`) है। Status queries, result queries, export-status queries और deletion कोई नया charge create नहीं करते।
- Timeout के बाद, दूसरी प्रस्तुति बनाने के बजाय saved task को query करें। [Billing and Errors](https://openapi.felo.ai/hi/docs/data-api/guides/felo-billing.md) देखें।