Felo APIs

PPT Task API

Cipta tugas penjanaan PPT, senaraikan tema dan pertanyaan endpoint tugas kongsi.

POST/v2/ppts

Pengesahan

Bearer API key

Jenis kandungan

application/json

Nota had kadar

Had khusus endpoint mungkin terpakai.

LiveDoc API Landing Page Task API

PPT Task API menyediakan keupayaan penjanaan PPT tak segerak. Anda boleh mencipta tugasan dan kemudian meninjau status tugasan melalui task_id. Anda juga boleh menyemak imbas tema PPT yang tersedia dan mengaplikasikannya semasa mencipta tugasan.

Ini ialah API tak segerak. Untuk corak hantar, tinjau, dan ambil yang dikongsi, lihat Tugasan Tak Segerak.

Pengesahan

Semua permintaan memerlukan Kunci API dalam pengepala Authorization:

Authorization: Bearer YOUR_API_KEY

Guna dengan Ejen AI

Untuk mencipta slaid daripada Ejen, pasang pakej lengkap felo-ai dan bukannya subset Skill yang tetap. Pemasangnya menemui secara dinamik setiap direktori pakej yang mengandungi SKILL.md, termasuk Skill PPT dan penambahan pada masa hadapan. Pasang semua Skill yang ditemui dalam direktori asli untuk Ejen anda: ~/.codex/skills Codex, ~/.claude/skills Claude Code, ~/.agents/skills OpenClaw, atau ~/.hermes/skills Hermes Agent. Ikuti panduan persediaan Ejen AI manual untuk konfigurasi dan pengesahan kunci API khusus platform.

1. Senaraikan Tema PPT

Tanyakan tema PPT yang tersedia dengan penomboran halaman, carian kata kunci, serta penapisan bahasa dan jenis.

Endpoint

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

Parameter Pertanyaan

Parameter	Jenis	Wajib	Penerangan
`lang`	string	Tidak	Kod bahasa untuk kandungan setempat (contohnya `en`, `zh-Hans`). Lalai: `en`
`type`	string	Tidak	Tapis mengikut jenis tema (contohnya `default`, `custom`)
`keyword`	string	Tidak	Kata kunci carian, sepadan dengan tajuk tema
`page`	integer	Tidak	Nombor halaman, bermula dari 1. Lalai: `1`
`size`	integer	Tidak	Saiz halaman, maksimum 100. Lalai: `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 Berjaya (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"
      }
    ]
  }
}

Medan Respons Tema

Medan	Jenis	Penerangan
`total`	integer	Jumlah bilangan tema yang sepadan dengan penapis
`page`	integer	Nombor halaman semasa
`size`	integer	Saiz halaman
`items`	array	Senarai objek tema
`items[].id`	string	ID tema, gunakan sebagai `ai_theme_id` semasa mencipta PPT
`items[].title`	string	Tajuk tema (setempat)
`items[].subtitle`	string	Sari kata tema (setempat)
`items[].description`	string	Penerangan tema (setempat)

2. Cipta Tugasan PPT

Endpoint

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

Pengepala Permintaan

Pengepala	Wajib	Penerangan
`Authorization`	Ya	Kunci API anda dalam format `Bearer YOUR_API_KEY`
`Content-Type`	Ya	`application/json` atau `multipart/form-data`

Isi Badan Permintaan

Parameter	Jenis	Wajib	Penerangan
`query`	string	Ya	Gesaan permintaan penjanaan PPT
`livedoc_short_id`	string	Tidak	ID pendek LiveDoc sedia ada untuk dikaitkan dengan sesi PPT. Jika ditinggalkan, LiveDoc baharu dicipta secara automatik.
`resource_ids`	array of strings	Tidak	Senarai ID sumber LiveDoc untuk digunakan sebagai konteks penjanaan PPT
`ppt_config`	object	Tidak	Pilihan konfigurasi PPT
`ppt_config.ai_theme_id`	string	Tidak	ID tema daripada endpoint Senaraikan 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"
    }
  }'

Cipta daripada Fail yang Dimuat Naik

Gunakan multipart/form-data untuk memuat naik satu fail dan mencipta tugasan PPT dalam satu permintaan. Platform memuat naik fail sebagai sumber LiveDoc terlebih dahulu, kemudian menghantar ID sumbernya kepada tugasan PPT.

Bahagian	Jenis	Wajib	Penerangan
`query`	string	Ya	Gesaan permintaan penjanaan PPT
`file`	file	Ya	Fail sumber yang digunakan sebagai konteks PPT
`stream_protocol`	string	Tidak	Protokol penstriman; lalai kepada `message_center_v1`
`livedoc_short_id`	string	Tidak	LiveDoc sedia ada untuk menerima fail. LiveDoc baharu dicipta apabila ditinggalkan.
`ppt_config`	JSON	Tidak	Konfigurasi PPT dengan struktur yang sama seperti isi badan permintaan JSON. Hantar bahagian 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 mengenal pasti LiveDoc yang mengandungi sumber yang dimuat naik.

Respons Berjaya (200)

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

3. Tinjau Status Tugasan

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 Berjaya (200)

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

4. Tanyakan Maklumat Sejarah Tugasan

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

Medan Respons Sejarah

Medan	Jenis	Penerangan
`task_id`	string	ID tugasan
`task_status`	string	Status tugasan semasa
`ppt_biz_id`	string	ID perniagaan PPT (dipetakan daripada `thread_short_id` backend)
`ppt_url`	string	URL PPT, format: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Hadir untuk `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; rentetan kosong `""` apabila hiliran tidak memberikan butiran ralat
`ai_page_html`	string	Hadir apabila tugasan berjalan dalam mod AI_PAGE dan sejarah hiliran mengembalikan URL hasil HTML
`live_doc_short_id`	string	ID pendek LiveDoc. Untuk `COMPLETED` ia datang daripada `live_doc_short_id` hiliran; untuk status kegagalan terminal ia dikembalikan apabila tersedia
`live_doc_url`	string	URL LiveDoc yang sepadan dengan `live_doc_short_id`

Eksport PPTX

Selepas tugasan penjanaan PPT mencapai COMPLETED, hantar eksport tak segerak menggunakan ppt_business_id daripada respons cipta (atau ppt_biz_id daripada respons sejarah):

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 '{}'

Tinjau GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export dengan Kunci API Bearer yang sama setiap 2–5 saat. PPT tersebut mesti dimiliki oleh pemilik Kunci API. Kedua-dua endpoint mengembalikan data.status: NOT_STARTED, PROCESSING, COMPLETED, atau FAILED. Hanya COMPLETED menyertakan download_url dan expires_at.

URL muat turun bertandatangan tamat tempoh 30 minit selepas dikeluarkan. Panggil endpoint GET sekali lagi untuk URL baharu; ini tidak menjana semula PPTX. POST menggunakan application/json dan menerima {}. Mengulang POST semasa eksport sedang diproses tidak memulakan kerja lain; memanggilnya selepas selesai menjana semula PPTX dan dikenakan caj kredit eksport PPT sedia ada. Kredit tidak mencukupi mengembalikan HTTP 402. Had kadar khusus endpoint mungkin dikenakan; cuba semula kemudian pada HTTP 429. Eksport yang gagal boleh dihantar semula.

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

Syor Tinjauan

Gunakan task_id daripada respons cipta dan tinjau status setiap 2-5 saat sehingga status menjadi keadaan terminal.

Contoh status biasa:

RUNNING: tugasan masih diproses
COMPLETED: tugasan selesai dengan jayanya
FAILED / PENDING / EXPIRED / CANCELED: tugasan mencapai status terminal dengan error_message; live_doc_url juga dikembalikan apabila tersedia

Nilai status tidak diketahui mungkin muncul apabila backend berkembang; anggap ia bukan terminal melainkan didokumentasikan sebaliknya.

Kod Ralat

Kod	Status HTTP	Penerangan
`UNAUTHORIZED`	401	Kunci API tidak sah atau telah dibatalkan
`PPT_TASK_CREATE_FAILED`	502	Panggilan hiliran cipta tugasan gagal
`PPT_TASK_QUERY_FAILED`	502	Panggilan hiliran tanya status tugasan gagal