# Penjanaan dan Eksport PPT

Cipta persembahan, undi kemajuannya, eksport PPTX dan uruskan hayatnya.

Jana persembahan secara tak segerak, kemudian eksport fail PPTX. Pastikan langkah penjanaan dan eksport berasingan: tugas yang dicipta belum lagi menjadi fail siap.

Semua contoh menggunakan `FELO_API_KEY` daripada [gambaran keseluruhan](https://openapi.felo.ai/ms/docs/data-api/guides/felo-overview.md). Panggilan menggunakan **baki platform**, bukan kredit Felo Pro. Contoh respons adalah ilustratif; kandungan langsung dan medan pilihan berbeza.

## Aliran kerja dan pengecam

1. Cipta tugas penjanaan; simpan `task_id`, `ppt_business_id` dan `expires_at`.
2. Undi status penjanaan menggunakan `task_id`.
3. Baca hasil penjanaan menggunakan `task_id`.
4. Mulakan eksport PPTX menggunakan `ppt_business_id`.
5. Undi status eksport dan muat turun fail yang lengkap.
6. Secara pilihan padamkan persembahan lebih awal.

Dalam ruang letak laluan, `{business_id}` bermaksud **`ppt_business_id`** yang dipulangkan, bukan `task_id`, `resource_id` atau `livedoc_short_id`. Gunakan akaun API yang sama untuk keseluruhan aliran kerja. ID dalam contoh adalah ruang letak.

## 1. Cipta persembahan

`POST /api/v1/data/ppts`

| Medan | Jenis | Diperlukan | Makna |
|---|---|---|---|
| `query` | string | Ya | Arahan penjanaan, 1–25,000 aksara |
| `stream_protocol` | string | Tidak | Lalai `message_center_v1`; biasanya biarkan tanpa perubahan |
| `ppt_config` | object | Tidak | Konfigurasi pilihan; pelaksanaan semasa membaca `ai_theme_id` |
| `livedoc_short_id` | string | Tidak | ID konteks sedia ada, sehingga 100 aksara; mesti lulus semakan pemilikan API asli dan tamat tempoh |
| `resource_ids` | string array | Tidak | Sehingga 100 ID sumber UUID; tertakluk pada semakan akses konteks yang sama |

Untuk integrasi pertama, jangan sertakan medan konteks dan konfigurasi. Konteks yang dicipta melalui `/v2` tidak secara automatik layak untuk guna semula di sini.

```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 memulangkan pengecam pada akar:

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

Pengecam tambahan seperti `resource_id`, `stream_key` dan `thread_short_id` mungkin hadir. Respons ciptaan yang berjaya bermaksud tugas telah diterima, bukan bahawa penjanaan telah selesai. Bilangan slaid yang diminta ialah arahan; pengebilan menggunakan kiraan halaman yang benar-benar dijana.

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

### Baca peristiwa penjanaan dengan SSE

Jika penciptaan memulangkan `stream_key`, sambung serta-merta dengan Kunci API yang dimiliki oleh akaun yang sama. Jika tiada kunci strim dipulangkan, gunakan pertanyaan status dan hasil di bawah.

```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'
```

| Parameter pertanyaan | Makna |
|---|---|
| `format` | `raw` (lalai) mengekalkan rentetan `content`; `structured` menyahkod JSON yang sah kepada objek atau tatasusunan |
| `offset` | Kedudukan sambung semula huluan pilihan untuk penyambungan semula; jangan simpulkannya daripada kiraan peristiwa tempatan anda |

Baca setiap peristiwa SSE lengkap, nyahkod JSON luarnya, kemudian proses `content`. Peristiwa aplikasi `answer` membawa teks dalam `data.text`; `finished` menandakan penyiapan penjanaan dalam strim. Juga kendalikan isyarat huluan `done`, `[DONE]`, dan `error`. Jika sambungan terputus tanpa isyarat penyiapan, lakukan pertanyaan status tugas.

Gunakan peraturan penghuraian dan contoh klien dalam [SuperAgent SSE](https://openapi.felo.ai/ms/docs/api-reference/superagent.md#2-gunakan-strim-sse), dengan URL `/api/v1/data/conversations/stream/{stream_key}` dalam bahagian ini. Baca hasil tugas selepas strim tamat; eksport PPTX kekal sebagai langkah berasingan. Titik akhir ini tidak mendayakan `stream: true` pada `/api/v1/data/chat`.

## 2. Undi status penjanaan

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

Respons mempunyai rentetan `status` pada akar, contohnya `RUNNING` atau `COMPLETED`. Undi dengan selang terhad (contohnya, 2–5 saat) dan garis masa akhir. Teruskan ke hasil selepas selesai; kendalikan kegagalan dan status yang tidak dijangka tanpa menganggap kejayaan. Garis masa pengundian tidak membatalkan tugas.

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

## 3. Baca hasil penjanaan

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

Ini ialah **POST**, tanpa badan JSON diperlukan.

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

Baca `task_status` sebelum menggunakan `history_data`. Muatan sejarah boleh berubah mengikut tugas dan mungkin null. `ai_page_html` dan `thread_short_id` adalah pilihan. Respons ini bukan URL muat turun PPTX yang dijamin; gunakan eksport seterusnya.

## 4. Mulakan eksport 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}
```

Penjanaan mesti telah selesai sebelum anda mengeksport. Mengulang POST semasa eksport yang sama masih berjalan akan menggunakan semula eksport itu. Memulakan satu lagi eksport selepas selesai mencipta eksport baharu dan boleh menanggung caj tambahan. Gunakan GET untuk mengundi dan menyegarkan pautan muat turun.

## 5. Undi eksport dan muat turun

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

| Status | Tindakan seterusnya |
|---|---|
| `NOT_STARTED` | Hantar eksport sekali |
| `PROCESSING` | Tunggu, kemudian undi GET sekali lagi |
| `COMPLETED` | Baca `download_url` dan muat turun fail |
| `FAILED` | Periksa ralat dan keadaan tugas sebelum menghantar eksport baharu |

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

URL contoh adalah ilustratif. Gunakan URL bertandatangan sebenar daripada respons. Ia sah selama **30 minit**; status eksport GET boleh memulangkan pautan baharu sementara persembahan masih tersedia. Simpan fail dalam tempohnya. Jangan hantar kunci API Felo anda ke hos muat turun fail.

## 6. Padam persembahan

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

Kejayaan memulangkan **HTTP 204 tanpa badan**. Jangan hurainya sebagai JSON. Pemadaman semasa penjanaan sedang berjalan memulangkan 409.

## Hayat, pemilikan dan pengebilan

- Persembahan tamat tempoh **tujuh hari selepas penciptaan**. Pertanyaan dan eksport tidak memanjangkan tempoh ini. `expires_at` persembahan dan `expires_at` URL muat turun bertandatangan menerangkan hayat yang berbeza.
- Hanya akaun API yang mencipta boleh mengakses tugas dan persembahannya. Sumber yang hilang atau tidak boleh diakses boleh memulangkan 404; sumber yang tamat tempoh atau dipadam boleh memulangkan 410, atau 404 selepas pembersihan.
- Penjanaan dibilkan bagi setiap halaman yang dijana (`ppt.generate`). Di bawah pengebilan halaman, penciptaan menempah harga sepuluh halaman, kemudian menyelesaikan output sebenar yang berjaya dan melepaskan tempahan yang tidak digunakan. Akaun anda memerlukan baki tersedia yang mencukupi untuk tempahan walaupun prompt meminta lebih sedikit halaman.
- Eksport mempunyai harga permintaan berasingan (`ppt.export`). Pertanyaan status, pertanyaan hasil, pertanyaan status eksport dan pemadaman tidak mencipta caj baharu.
- Selepas tamat masa, lakukan pertanyaan terhadap tugas yang disimpan dan bukannya mencipta persembahan lain. Lihat [Pengebilan dan Ralat](https://openapi.felo.ai/ms/docs/data-api/guides/felo-billing.md).