# Tạo và xuất PPT

Tạo bản trình bày, thăm dò tiến độ, xuất tệp PPTX và quản lý vòng đời của nó.

Tạo một bản trình bày không đồng bộ, rồi xuất tệp PPTX. Giữ các bước tạo và xuất tách biệt: một tác vụ đã tạo chưa phải là một tệp hoàn chỉnh.

Tất cả ví dụ dùng `FELO_API_KEY` từ [tổng quan](https://openapi.felo.ai/vi/docs/data-api/guides/felo-overview.md). Các cuộc gọi sử dụng **số dư nền tảng**, không phải tín dụng Felo Pro. Các ví dụ phản hồi chỉ mang tính minh họa; nội dung thực tế và các trường tùy chọn sẽ thay đổi.

## Quy trình và định danh

1. Tạo tác vụ tạo; lưu `task_id`, `ppt_business_id` và `expires_at`.
2. Thăm dò trạng thái tạo bằng `task_id`.
3. Đọc kết quả tạo bằng `task_id`.
4. Bắt đầu xuất PPTX bằng `ppt_business_id`.
5. Thăm dò trạng thái xuất và tải tệp hoàn chỉnh.
6. Tùy chọn xóa bản trình bày sớm hơn.

Trong các chỗ giữ chỗ của tuyến đường, `{business_id}` nghĩa là **`ppt_business_id`** đã trả về, không phải `task_id`, `resource_id` hoặc `livedoc_short_id`. Hãy dùng cùng một tài khoản API cho toàn bộ quy trình. Các ID trong ví dụ chỉ là chỗ giữ chỗ.

## 1. Tạo bản trình bày

`POST /api/v1/data/ppts`

| Trường | Kiểu | Bắt buộc | Ý nghĩa |
|---|---|---|---|
| `query` | string | Có | Hướng dẫn tạo, 1–25.000 ký tự |
| `stream_protocol` | string | Không | Mặc định `message_center_v1`; thông thường nên để nguyên |
| `ppt_config` | object | Không | Cấu hình tùy chọn; cách triển khai hiện tại đọc `ai_theme_id` |
| `livedoc_short_id` | string | Không | ID ngữ cảnh hiện có, tối đa 100 ký tự; phải vượt qua kiểm tra quyền sở hữu và hết hạn của API gốc |
| `resource_ids` | mảng chuỗi | Không | Tối đa 100 ID tài nguyên UUID; chịu cùng kiểm tra truy cập ngữ cảnh |

Đối với tích hợp đầu tiên, hãy bỏ qua các trường ngữ cảnh và cấu hình. Một ngữ cảnh được tạo qua `/v2` không tự động đủ điều kiện để tái sử dụng ở đây.

```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 trả về các định danh ở gốc:

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

Các định danh bổ sung như `resource_id`, `stream_key` và `thread_short_id` có thể xuất hiện. Phản hồi tạo thành công có nghĩa là tác vụ đã được chấp nhận, không phải là việc tạo đã hoàn tất. Số lượng trang được yêu cầu chỉ là một chỉ dẫn; thanh toán dùng số trang thực tế được tạo.

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

### Đọc sự kiện tạo bằng SSE

Nếu việc tạo trả về `stream_key`, hãy kết nối ngay bằng API Key thuộc cùng tài khoản. Nếu không có stream key được trả về, hãy dùng các truy vấn trạng thái và kết quả bên dưới.

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

| Tham số truy vấn | Ý nghĩa |
|---|---|
| `format` | `raw` (mặc định) giữ nguyên chuỗi `content`; `structured` giải mã JSON hợp lệ thành object hoặc array |
| `offset` | Vị trí tiếp tục upstream tùy chọn để kết nối lại; đừng suy ra từ số sự kiện cục bộ của bạn |

Đọc từng sự kiện SSE hoàn chỉnh, giải mã JSON bên ngoài của nó, rồi xử lý `content`. Một sự kiện ứng dụng `answer` mang văn bản trong `data.text`; `finished` báo hiệu hoàn tất tạo trong luồng. Cũng hãy xử lý các tín hiệu upstream `done`, `[DONE]`, và `error`. Nếu kết nối đóng mà không có tín hiệu hoàn tất, hãy truy vấn trạng thái tác vụ.

Dùng các quy tắc phân tích và ví dụ client trong [SuperAgent SSE](https://openapi.felo.ai/vi/docs/api-reference/superagent.md#2-ti-u-th-lu-ng-sse), với URL `/api/v1/data/conversations/stream/{stream_key}` của mục này. Đọc kết quả tác vụ sau khi luồng kết thúc; xuất PPTX vẫn là một bước riêng. Endpoint này không bật `stream: true` trên `/api/v1/data/chat`.

## 2. Thăm dò trạng thái tạo

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

Phản hồi có một chuỗi `status` ở gốc, ví dụ `RUNNING` hoặc `COMPLETED`. Thăm dò theo khoảng thời gian có giới hạn (ví dụ, 2–5 giây) và một hạn chót. Tiếp tục sang kết quả sau khi hoàn tất; xử lý lỗi và trạng thái bất thường mà không mặc định là thành công. Hạn chót thăm dò không hủy tác vụ.

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

## 3. Đọc kết quả tạo

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

Đây là một **POST**, không cần phần thân JSON.

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

Đọc `task_status` trước khi dùng `history_data`. Payload lịch sử có thể thay đổi theo tác vụ và có thể là null. `ai_page_html` và `thread_short_id` là tùy chọn. Phản hồi này không phải là một URL tải xuống PPTX được đảm bảo; hãy dùng xuất ở bước tiếp theo.

## 4. Bắt đầu xuất 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}
```

Việc tạo phải hoàn tất trước khi bạn xuất. Lặp lại POST trong khi cùng một lần xuất đang chạy sẽ tái sử dụng nó. Bắt đầu một lần xuất khác sau khi hoàn tất sẽ tạo một lần xuất mới và có thể phát sinh thêm phí. Dùng GET để thăm dò và làm mới liên kết tải xuống.

## 5. Thăm dò xuất và tải xuống

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

| Trạng thái | Hành động tiếp theo |
|---|---|
| `NOT_STARTED` | Gửi xuất một lần |
| `PROCESSING` | Chờ, rồi thăm dò GET lại |
| `COMPLETED` | Đọc `download_url` và tải tệp xuống |
| `FAILED` | Kiểm tra lỗi và trạng thái tác vụ trước khi gửi một lần xuất mới |

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

URL ví dụ chỉ mang tính minh họa. Hãy dùng URL có ký số thực tế từ phản hồi. Nó có hiệu lực trong **30 phút**; trạng thái xuất GET có thể trả về một liên kết mới trong khi bản trình bày vẫn còn khả dụng. Hãy lưu tệp trong thời hạn đó. Không gửi khóa Felo API của bạn tới máy chủ tải tệp.

## 6. Xóa bản trình bày

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

Thành công trả về **HTTP 204 không có nội dung**. Đừng phân tích nó như JSON. Xóa trong khi tạo đang chạy sẽ trả về 409.

## Vòng đời, quyền sở hữu và thanh toán

- Bản trình bày hết hạn **bảy ngày sau khi tạo**. Các truy vấn và xuất không kéo dài khoảng thời gian này. `expires_at` của bản trình bày và `expires_at` của URL tải xuống có chữ ký mô tả các vòng đời khác nhau.
- Chỉ tài khoản API đã tạo mới có thể truy cập các tác vụ và bản trình bày của nó. Một tài nguyên bị thiếu hoặc không thể truy cập có thể trả về 404; một tài nguyên đã hết hạn hoặc đã bị xóa có thể trả về 410, hoặc 404 sau khi dọn dẹp.
- Việc tạo được tính phí theo từng trang được tạo (`ppt.generate`). Theo định giá theo trang, khi tạo sẽ giữ chỗ cho giá của mười trang, rồi quyết toán đầu ra thành công thực tế và giải phóng phần giữ chỗ chưa dùng. Tài khoản của bạn cần đủ số dư khả dụng cho khoản giữ chỗ ngay cả khi prompt yêu cầu ít trang hơn.
- Xuất có một mức giá yêu cầu riêng (`ppt.export`). Các truy vấn trạng thái, truy vấn kết quả, truy vấn trạng thái xuất và thao tác xóa không tạo ra phí mới.
- Sau khi timeout, hãy truy vấn tác vụ đã lưu thay vì tạo một bản trình bày khác. Xem [Thanh toán và Lỗi](https://openapi.felo.ai/vi/docs/data-api/guides/felo-billing.md).