# Cipta Persembahan Felo

POST /api/v1/data/ppts

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.





## 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`.



## 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).