Felo APIs

PPT Task API

Tạo tác vụ tạo PPT, liệt kê chủ đề và truy vấn endpoint tác vụ dùng chung.

POST/v2/ppts

Xác thực

Bearer API key

Loại nội dung

application/json

Ghi chú về giới hạn

Có thể áp dụng giới hạn riêng cho endpoint.

LiveDoc API Landing Page Task API

PPT Task API cung cấp khả năng tạo PPT bất đồng bộ. Bạn có thể tạo tác vụ rồi thăm dò trạng thái tác vụ bằng task_id. Bạn cũng có thể duyệt các chủ đề PPT hiện có và áp dụng chúng khi tạo tác vụ.

Đây là một API bất đồng bộ. Về mô hình gửi, thăm dò và lấy kết quả dùng chung, xem Tác vụ bất đồng bộ.

Xác thực

Mọi yêu cầu đều cần khóa API trong header Authorization:

Authorization: Bearer YOUR_API_KEY

Dùng với AI Agent

Để tạo slide từ một Agent, hãy cài gói felo-ai đầy đủ thay vì một tập con Skill cố định. Trình cài đặt của nó tự động khám phá mọi thư mục gói có chứa SKILL.md, bao gồm Skill PPT và các bổ sung trong tương lai. Hãy cài mọi Skill được phát hiện vào thư mục gốc của Agent: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills hoặc Hermes Agent ~/.hermes/skills. Làm theo hướng dẫn thiết lập AI Agent thủ công để biết cách cấu hình khóa API và xác minh riêng cho từng nền tảng.

1. Danh sách chủ đề PPT

Truy vấn các chủ đề PPT hiện có với phân trang, tìm kiếm theo từ khóa, lọc theo ngôn ngữ và loại.

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`lang`	string	Không	Mã ngôn ngữ cho nội dung bản địa hóa (ví dụ `en`, `zh-Hans`). Mặc định: `en`
`type`	string	Không	Lọc theo loại chủ đề (ví dụ `default`, `custom`)
`keyword`	string	Không	Từ khóa tìm kiếm, khớp với tiêu đề chủ đề
`page`	integer	Không	Số trang, bắt đầu từ 1. Mặc định: `1`
`size`	integer	Không	Kích thước trang, tối đa 100. Mặc định: `20`

Ví dụ

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'

Phản hồi thành công (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"
      }
    ]
  }
}

Các trường phản hồi chủ đề

Trường	Kiểu	Mô tả
`total`	integer	Tổng số chủ đề khớp với bộ lọc
`page`	integer	Số trang hiện tại
`size`	integer	Kích thước trang
`items`	array	Danh sách các đối tượng chủ đề
`items[].id`	string	ID chủ đề, dùng làm `ai_theme_id` khi tạo PPT
`items[].title`	string	Tiêu đề chủ đề (đã bản địa hóa)
`items[].subtitle`	string	Phụ đề chủ đề (đã bản địa hóa)
`items[].description`	string	Mô tả chủ đề (đã bản địa hóa)

2. Tạo tác vụ PPT

Endpoint

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

Header yêu cầu

Header	Bắt buộc	Mô tả
`Authorization`	Có	Khóa API của bạn theo định dạng `Bearer YOUR_API_KEY`
`Content-Type`	Có	`application/json` hoặc `multipart/form-data`

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`query`	string	Có	Câu lệnh yêu cầu tạo PPT
`livedoc_short_id`	string	Không	Short ID của LiveDoc hiện có để liên kết với phiên PPT. Nếu bỏ qua, một LiveDoc mới sẽ được tạo tự động.
`resource_ids`	array of strings	Không	Danh sách ID tài nguyên LiveDoc để dùng làm ngữ cảnh cho việc tạo PPT
`ppt_config`	object	Không	Các tùy chọn cấu hình PPT
`ppt_config.ai_theme_id`	string	Không	ID chủ đề từ endpoint Danh sách chủ đề PPT

Ví dụ

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

Tạo từ tệp đã tải lên

Dùng multipart/form-data để tải một tệp lên và tạo tác vụ PPT trong một yêu cầu duy nhất. Nền tảng tải tệp lên thành tài nguyên LiveDoc trước, sau đó truyền resource ID của nó cho tác vụ PPT.

Phần	Kiểu	Bắt buộc	Mô tả
`query`	string	Có	Câu lệnh yêu cầu tạo PPT
`file`	file	Có	Tệp nguồn dùng làm ngữ cảnh PPT
`stream_protocol`	string	Không	Giao thức truyền trực tiếp; mặc định là `message_center_v1`
`livedoc_short_id`	string	Không	LiveDoc hiện có để nhận tệp. Một LiveDoc mới được tạo khi bỏ qua.
`ppt_config`	JSON	Không	Cấu hình PPT có cùng cấu trúc như nội dung yêu cầu JSON. Gửi phần này dưới dạng `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]'

Phản hồi dùng cùng lược đồ như yêu cầu JSON. livedoc_short_id được trả về xác định LiveDoc chứa tài nguyên đã tải lên.

Phản hồi thành công (200)

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

3. Truy vấn trạng thái tác vụ

Endpoint

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

Ví dụ

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'

Phản hồi thành công (200)

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

4. Truy vấn thông tin lịch sử của tác vụ

Endpoint

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

Ví dụ

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'

Phản hồi 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"
  }
}

Phản hồi 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"
  }
}

Phản hồi 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"
  }
}

Phản hồi 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"
  }
}

Các trường phản hồi lịch sử

Trường	Kiểu	Mô tả
`task_id`	string	Task ID
`task_status`	string	Trạng thái hiện tại của tác vụ
`ppt_biz_id`	string	ID nghiệp vụ PPT (ánh xạ từ `thread_short_id` của backend)
`ppt_url`	string	URL PPT, định dạng: `https://felo.ai/slides/{ppt_biz_id}`
`error_message`	string	Có với `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; chuỗi rỗng `""` khi hạ nguồn không cung cấp chi tiết lỗi
`ai_page_html`	string	Có khi tác vụ chạy ở chế độ AI_PAGE và lịch sử hạ nguồn trả về URL kết quả HTML
`live_doc_short_id`	string	Short ID của LiveDoc. Với `COMPLETED`, nó đến từ `live_doc_short_id` của hạ nguồn; với các trạng thái thất bại kết thúc, nó được trả về khi có
`live_doc_url`	string	URL LiveDoc tương ứng với `live_doc_short_id`

Xuất PPTX

Sau khi tác vụ tạo PPT đạt COMPLETED, hãy gửi một yêu cầu xuất bất đồng bộ bằng ppt_business_id từ phản hồi tạo (hoặc ppt_biz_id từ phản hồi lịch sử):

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

Thăm dò GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export với cùng khóa API Bearer mỗi 2–5 giây. Chủ sở hữu khóa API phải sở hữu PPT đó. Cả hai endpoint đều trả về data.status: NOT_STARTED, PROCESSING, COMPLETED hoặc FAILED. Chỉ COMPLETED bao gồm download_url và expires_at.

URL tải xuống đã ký hết hạn 30 phút sau khi được cấp. Hãy gọi lại endpoint GET để lấy URL mới; việc này không tạo lại PPTX. POST dùng application/json và chấp nhận {}. Lặp lại POST trong khi một lần xuất đang xử lý sẽ không bắt đầu một tác vụ khác; gọi nó sau khi hoàn tất sẽ tạo lại PPTX và phát sinh khoản phí tín dụng xuất PPT hiện có. Không đủ tín dụng trả về HTTP 402. Giới hạn tần suất riêng của endpoint có thể áp dụng; hãy thử lại sau khi gặp HTTP 429. Một lần xuất thất bại có thể được gửi lại.

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

Khuyến nghị thăm dò

Dùng task_id từ phản hồi tạo và thăm dò trạng thái mỗi 2-5 giây cho đến khi trạng thái trở thành trạng thái kết thúc.

Ví dụ trạng thái thường gặp:

RUNNING: tác vụ vẫn đang xử lý
COMPLETED: tác vụ đã hoàn tất thành công
FAILED / PENDING / EXPIRED / CANCELED: tác vụ đã đạt trạng thái kết thúc kèm error_message; live_doc_url cũng được trả về khi có

Các giá trị trạng thái chưa biết có thể xuất hiện khi backend phát triển; hãy coi chúng là chưa kết thúc trừ khi tài liệu nói khác.

Mã lỗi

Mã	Trạng thái HTTP	Mô tả
`UNAUTHORIZED`	401	Khóa API không hợp lệ hoặc đã bị thu hồi
`PPT_TASK_CREATE_FAILED`	502	Lệnh gọi hạ nguồn tạo tác vụ thất bại
`PPT_TASK_QUERY_FAILED`	502	Lệnh gọi hạ nguồn truy vấn trạng thái tác vụ thất bại