# Pembuatan dan Ekspor PPT

Buat presentasi, pantau progresnya, ekspor PPTX, dan kelola masa hidupnya.

Hasilkan presentasi secara asinkron, lalu ekspor file PPTX. Pisahkan langkah pembuatan dan ekspor: tugas yang dibuat belum merupakan file yang selesai.

Semua contoh menggunakan `FELO_API_KEY` dari [gambaran umum](https://openapi.felo.ai/id/docs/data-api/guides/felo-overview.md). Panggilan menggunakan **saldo platform**, bukan kredit Felo Pro. Contoh respons bersifat ilustratif; konten langsung dan bidang opsional bervariasi.

## Alur kerja dan pengenal

1. Buat tugas pembuatan; simpan `task_id`, `ppt_business_id`, dan `expires_at`.
2. Poll status pembuatan menggunakan `task_id`.
3. Baca hasil pembuatan menggunakan `task_id`.
4. Mulai ekspor PPTX menggunakan `ppt_business_id`.
5. Poll status ekspor dan unduh file yang selesai.
6. Opsional, hapus presentasi lebih awal.

Dalam placeholder rute, `{business_id}` berarti **`ppt_business_id`** yang dikembalikan, bukan `task_id`, `resource_id`, atau `livedoc_short_id`. Gunakan akun API yang sama untuk seluruh alur kerja. ID pada contoh adalah placeholder.

## 1. Buat presentasi

`POST /api/v1/data/ppts`

| Bidang | Tipe | Wajib | Arti |
|---|---|---|---|
| `query` | string | Ya | Instruksi pembuatan, 1–25.000 karakter |
| `stream_protocol` | string | Tidak | Default `message_center_v1`; biasanya biarkan tidak berubah |
| `ppt_config` | object | Tidak | Konfigurasi opsional; implementasi saat ini membaca `ai_theme_id` |
| `livedoc_short_id` | string | Tidak | ID konteks yang sudah ada, hingga 100 karakter; harus lolos pemeriksaan kepemilikan dan kedaluwarsa API native |
| `resource_ids` | string array | Tidak | Hingga 100 ID resource UUID; tunduk pada pemeriksaan akses konteks yang sama |

Untuk integrasi pertama, hilangkan bidang konteks dan konfigurasi. Konteks yang dibuat melalui `/v2` tidak otomatis memenuhi syarat untuk digunakan kembali 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 mengembalikan pengenal di root:

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

Pengenal tambahan seperti `resource_id`, `stream_key`, dan `thread_short_id` mungkin ada. Respons pembuatan yang sukses berarti tugas telah diterima, bukan bahwa pembuatan telah selesai. Jumlah slide yang diminta adalah instruksi; penagihan menggunakan jumlah halaman yang sebenarnya dihasilkan.

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

### Baca peristiwa pembuatan dengan SSE

Jika pembuatan mengembalikan `stream_key`, segera sambungkan dengan API Key yang dimiliki akun yang sama. Jika tidak ada stream key yang dikembalikan, gunakan kueri 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 kueri | Arti |
|---|---|
| `format` | `raw` (default) mempertahankan string `content`; `structured` mendekode JSON valid menjadi objek atau array |
| `offset` | Posisi lanjut upstream opsional untuk penyambungan ulang; jangan menyimpulkannya dari jumlah peristiwa lokal Anda |

Baca setiap event SSE yang lengkap, dekode JSON luarnya, lalu proses `content`. Event aplikasi `answer` membawa teks di `data.text`; `finished` menandakan selesainya pembuatan di stream. Tangani juga sinyal upstream `done`, `[DONE]`, dan `error`. Jika koneksi ditutup tanpa sinyal selesai, kueri status tugas.

Gunakan aturan parsing dan contoh klien dalam [SSE SuperAgent](https://openapi.felo.ai/id/docs/api-reference/superagent.md#2-konsumsi-stream-sse), dengan URL bagian ini `/api/v1/data/conversations/stream/{stream_key}`. Baca hasil tugas setelah stream berakhir; ekspor PPTX tetap merupakan langkah terpisah. Endpoint ini tidak mengaktifkan `stream: true` pada `/api/v1/data/chat`.

## 2. Poll status pembuatan

`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 memiliki string `status` di root, misalnya `RUNNING` atau `COMPLETED`. Lakukan polling dengan interval terbatas (misalnya, 2–5 detik) dan tenggat waktu. Lanjutkan ke hasil setelah selesai; tangani kegagalan dan status tak terduga tanpa mengasumsikan sukses. Tenggat polling tidak membatalkan tugas.

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

## 3. Baca hasil pembuatan

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

Ini adalah **POST**, tanpa body JSON yang 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`. Payload histori dapat bervariasi menurut tugas dan mungkin bernilai null. `ai_page_html` dan `thread_short_id` bersifat opsional. Respons ini bukan URL unduhan PPTX yang dijamin; gunakan ekspor berikutnya.

## 4. Mulai ekspor 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}
```

Pembuatan harus sudah selesai sebelum Anda mengekspor. Mengulangi POST saat ekspor yang sama sedang berjalan akan menggunakan ulang ekspor itu. Memulai ekspor lain setelah selesai akan membuat ekspor baru dan dapat menimbulkan biaya baru. Gunakan GET untuk polling dan menyegarkan tautan unduhan.

## 5. Poll ekspor dan unduh

`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 berikutnya |
|---|---|---|
| `NOT_STARTED` | Kirim ekspor sekali |
| `PROCESSING` | Tunggu, lalu polling GET lagi |
| `COMPLETED` | Baca `download_url` dan unduh file |
| `FAILED` | Periksa kesalahan dan status tugas sebelum mengirim ekspor baru |

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

Contoh URL bersifat ilustratif. Gunakan URL bertanda tangan yang sebenarnya dari respons. URL ini berlaku selama **30 menit**; status ekspor GET dapat mengembalikan tautan baru selama presentasi masih tersedia. Simpan file dalam masa berlakunya. Jangan kirim kunci API Felo Anda ke host pengunduhan file.

## 6. Hapus presentasi

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

Keberhasilan mengembalikan **HTTP 204 tanpa body**. Jangan memprosesnya sebagai JSON. Penghapusan saat pembuatan sedang berjalan mengembalikan 409.

## Masa hidup, kepemilikan, dan penagihan

- Presentasi kedaluwarsa **tujuh hari setelah dibuat**. Kueri dan ekspor tidak memperpanjang periode ini. `expires_at` presentasi dan `expires_at` URL unduhan bertanda tangan menjelaskan masa hidup yang berbeda.
- Hanya akun API yang membuat yang dapat mengakses tugas dan presentasinya. Resource yang hilang atau tidak dapat diakses dapat mengembalikan 404; resource yang kedaluwarsa atau dihapus dapat mengembalikan 410, atau 404 setelah pembersihan.
- Pembuatan ditagihkan per halaman yang dihasilkan (`ppt.generate`). Di bawah harga per halaman, pembuatan mencadangkan harga sepuluh halaman, lalu menyelesaikan output sukses aktual dan melepaskan cadangan yang tidak terpakai. Akun Anda membutuhkan saldo tersedia yang cukup untuk cadangan tersebut meskipun prompt meminta lebih sedikit halaman.
- Ekspor memiliki harga permintaan terpisah (`ppt.export`). Kueri status, kueri hasil, kueri status ekspor, dan penghapusan tidak menimbulkan biaya baru.
- Setelah waktu habis, kueri tugas yang disimpan, bukan membuat presentasi lain. Lihat [Penagihan dan Kesalahan](https://openapi.felo.ai/id/docs/data-api/guides/felo-billing.md).