Felo APIs

PPT Task API

Buat tugas pembuatan PPT, daftarkan tema, dan kueri endpoint tugas bersama.

POST/v2/ppts

Autentikasi

Bearer API key

Tipe konten

application/json

Catatan batas laju

Batas khusus endpoint dapat berlaku.

LiveDoc API Landing Page Task API

PPT Task API menyediakan kemampuan pembuatan PPT secara asinkron. Anda dapat membuat tugas lalu melakukan polling status tugas melalui task_id. Anda juga dapat menelusuri tema PPT yang tersedia dan menerapkannya saat membuat tugas.

Ini adalah API asinkron. Untuk pola pengiriman, polling, dan pengambilan yang sama, lihat Tugas Asinkron.

Autentikasi

Semua permintaan memerlukan Kunci API di header Authorization:

Authorization: Bearer YOUR_API_KEY

Penggunaan dengan Agen AI

Untuk membuat slide dari Agen, pasang paket felo-ai lengkap, bukan subset Skill yang tetap. Installer-nya menemukan setiap direktori paket yang berisi SKILL.md secara dinamis, termasuk PPT Skill dan penambahan di masa mendatang. Pasang semua Skill yang ditemukan di direktori bawaan Agen Anda: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills, atau Hermes Agent ~/.hermes/skills. Ikuti panduan penyiapan Agen AI manual untuk konfigurasi dan verifikasi kunci API yang spesifik per platform.

1. Menampilkan Daftar Tema PPT

Kueri tema PPT yang tersedia dengan paginasi, pencarian kata kunci, serta filter bahasa dan tipe.

Endpoint

GET https://openapi.felo.ai/v2/ppt-themes

Parameter Kueri

Parameter	Tipe	Wajib	Deskripsi
`lang`	string	Tidak	Kode bahasa untuk konten yang dilokalkan (mis. `en`, `zh-Hans`). Default: `en`
`type`	string	Tidak	Filter berdasarkan tipe tema (mis. `default`, `custom`)
`keyword`	string	Tidak	Kata kunci pencarian, dicocokkan dengan judul tema
`page`	integer	Tidak	Nomor halaman, dimulai dari 1. Default: `1`
`size`	integer	Tidak	Ukuran halaman, maksimal 100. Default: `20`

Contoh

curl -X GET 'https://openapi.felo.ai/v2/ppt-themes?lang=en&page=1&size=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Respons Berhasil (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 8,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": "43122897-0d3c-4c9e-ae19-20527ad36c04",
        "title": "Inspiration Themes",
        "subtitle": "AI-tailored visual solutions",
        "description": "Style and layout, both crafted by AI from your content in real time"
      }
    ]
  }
}

Field Respons Tema

Field	Tipe	Deskripsi
`total`	integer	Jumlah total tema yang cocok dengan filter
`page`	integer	Nomor halaman saat ini
`size`	integer	Ukuran halaman
`items`	array	Daftar objek tema
`items[].id`	string	ID tema, gunakan ini sebagai `ai_theme_id` saat membuat PPT
`items[].title`	string	Judul tema (dilokalkan)
`items[].subtitle`	string	Subtitle tema (dilokalkan)
`items[].description`	string	Deskripsi tema (dilokalkan)

2. Membuat Tugas PPT

Endpoint

POST https://openapi.felo.ai/v2/ppts

Header Permintaan

Header	Wajib	Deskripsi
`Authorization`	Ya	Kunci API Anda dalam format `Bearer YOUR_API_KEY`
`Content-Type`	Ya	`application/json` atau `multipart/form-data`

Isi Permintaan

Parameter	Tipe	Wajib	Deskripsi
`query`	string	Ya	Prompt permintaan pembuatan PPT
`livedoc_short_id`	string	Tidak	Short ID LiveDoc yang sudah ada untuk dikaitkan dengan sesi PPT. Jika dihilangkan, LiveDoc baru akan dibuat secara otomatis.
`resource_ids`	array of strings	Tidak	Daftar ID resource LiveDoc yang digunakan sebagai konteks pembuatan PPT
`ppt_config`	object	Tidak	Opsi konfigurasi PPT
`ppt_config.ai_theme_id`	string	Tidak	ID tema dari endpoint Menampilkan Daftar Tema PPT

Contoh

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Felo, 2 pages",
    "ppt_config": {
      "ai_theme_id": "02968979-a69f-42c4-b136-de02c40ab2d7"
    }
  }'

Membuat dari File yang Diunggah

Gunakan multipart/form-data untuk mengunggah satu file dan membuat tugas PPT dalam satu permintaan. Platform mengunggah file sebagai resource LiveDoc terlebih dahulu, lalu meneruskan ID resource-nya ke tugas PPT.

Bagian	Tipe	Wajib	Deskripsi
`query`	string	Ya	Prompt permintaan pembuatan PPT
`file`	file	Ya	File sumber yang digunakan sebagai konteks PPT
`stream_protocol`	string	Tidak	Protokol streaming; default `message_center_v1`
`livedoc_short_id`	string	Tidak	LiveDoc yang sudah ada untuk menerima file. LiveDoc baru dibuat jika dihilangkan.
`ppt_config`	JSON	Tidak	Konfigurasi PPT dengan struktur yang sama seperti isi permintaan JSON. Kirim bagian ini sebagai `application/json`.

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=Create a 10-page presentation based on this report' \
  -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \
  -F '[email protected]'

Respons menggunakan skema yang sama seperti permintaan JSON. livedoc_short_id yang dikembalikan mengidentifikasi LiveDoc yang berisi resource yang diunggah.

Respons Berhasil (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3",
    "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr",
    "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9"
  }
}

3. Menanyakan Status Tugas

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/status

Contoh

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Respons Berhasil (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "RUNNING"
  }
}

4. Menanyakan Informasi Historis Tugas

Endpoint

GET https://openapi.felo.ai/v2/tasks/{task_id}/historical

Contoh

curl -X GET 'https://openapi.felo.ai/v2/tasks/019cb17e-9e23-3d40-4447-48a651249460/historical' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Respons RUNNING

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "RUNNING",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Respons COMPLETED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "COMPLETED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Respons COMPLETED (AI_PAGE)

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621",
    "task_status": "COMPLETED",
    "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ",
    "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ",
    "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ"
  }
}

Respons FAILED / PENDING / EXPIRED / CANCELED

{
  "status": "ok",
  "message": null,
  "data": {
    "task_id": "019cb17e-9e23-3d40-4447-48a651249460",
    "task_status": "FAILED",
    "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx",
    "error_message": "PPT generation failed",
    "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx",
    "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx"
  }
}

Field Respons Historis

Field	Tipe	Deskripsi
`task_id`	string	ID tugas
`task_status`	string	Status tugas saat ini
`ppt_biz_id`	string	ID bisnis PPT (dipetakan dari `thread_short_id` backend)
`ppt_url`	string	URL PPT, format: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Ada untuk `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; string kosong `""` jika layanan downstream tidak menyediakan detail error
`ai_page_html`	string	Ada jika tugas berjalan dalam mode AI_PAGE dan data historis downstream mengembalikan URL hasil HTML
`live_doc_short_id`	string	Short ID LiveDoc. Untuk `COMPLETED` berasal dari `live_doc_short_id` downstream; untuk status kegagalan terminal dikembalikan jika tersedia
`live_doc_url`	string	URL LiveDoc yang sesuai dengan `live_doc_short_id`

Ekspor PPTX

Setelah tugas pembuatan PPT mencapai COMPLETED, kirim ekspor asinkron menggunakan ppt_business_id dari respons pembuatan (atau ppt_biz_id dari respons historis):

curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Lakukan polling GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export dengan Kunci API Bearer yang sama setiap 2–5 detik. Pemilik Kunci API harus memiliki PPT tersebut. Kedua endpoint mengembalikan data.status: NOT_STARTED, PROCESSING, COMPLETED, atau FAILED. Hanya COMPLETED yang menyertakan download_url dan expires_at.

URL unduhan bertanda tangan kedaluwarsa 30 menit setelah diterbitkan. Panggil endpoint GET lagi untuk mendapatkan URL baru; ini tidak membuat ulang PPTX. POST menggunakan application/json dan menerima {}. Mengulang POST saat ekspor sedang diproses tidak memulai tugas lain; memanggilnya setelah selesai akan membuat ulang PPTX dan dikenakan biaya kredit ekspor PPT yang berlaku. Jika kredit tidak mencukupi, API mengembalikan HTTP 402. Batas laju khusus endpoint dapat berlaku; coba lagi nanti pada HTTP 429. Ekspor yang gagal dapat dikirim ulang.

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "COMPLETED",
    "download_url": "https://example.com/presentation.pptx?signature=...",
    "expires_at": "2026-09-29T10:30:00Z"
  }
}

Rekomendasi Polling

Gunakan task_id dari respons pembuatan dan lakukan polling status setiap 2-5 detik hingga status menjadi keadaan terminal.

Contoh status umum:

RUNNING: tugas masih diproses
COMPLETED: tugas selesai dengan berhasil
FAILED / PENDING / EXPIRED / CANCELED: tugas mencapai status terminal dengan error_message; live_doc_url juga dikembalikan jika tersedia

Nilai status yang tidak dikenal dapat muncul seiring perkembangan backend; perlakukan status tersebut sebagai non-terminal kecuali didokumentasikan lain.

Kode Error

Kode	Status HTTP	Deskripsi
`UNAUTHORIZED`	401	Kunci API tidak valid atau sudah dicabut
`PPT_TASK_CREATE_FAILED`	502	Panggilan downstream pembuatan tugas gagal
`PPT_TASK_QUERY_FAILED`	502	Panggilan downstream kueri status tugas gagal