# Felo 프레젠테이션 만들기

POST /api/v1/data/ppts

프레젠테이션을 비동기로 생성한 다음 PPTX 파일을 내보내세요. 생성과 내보내기 단계를 분리하세요. 생성된 작업은 아직 완성된 파일이 아닙니다.

모든 예시는 [개요](https://openapi.felo.ai/ko/docs/data-api/guides/felo-overview.md)의 `FELO_API_KEY`를 사용합니다. 호출은 Felo Pro 크레딧이 아니라 **플랫폼 잔액**을 사용합니다. 응답 예시는 설명용이며, 실제 콘텐츠와 선택적 필드는 달라질 수 있습니다.





## 1. 프레젠테이션 만들기

`POST /api/v1/data/ppts`

| 필드 | 유형 | 필수 | 의미 |
|---|---|---|---|
| `query` | string | 예 | 생성 지침, 1–25,000자 |
| `stream_protocol` | string | 아니오 | 기본값 `message_center_v1`; 일반적으로 변경하지 마세요 |
| `ppt_config` | object | 아니오 | 선택적 설정; 현재 구현은 `ai_theme_id`를 읽습니다 |
| `livedoc_short_id` | string | 아니오 | 기존 컨텍스트 ID, 최대 100자; 기본 API 소유권 및 만료 검사를 통과해야 합니다 |
| `resource_ids` | string array | 아니오 | 최대 100개의 UUID 리소스 ID; 동일한 컨텍스트 접근 검사를 받습니다 |

첫 통합에서는 컨텍스트 및 설정 필드를 생략하세요. `/v2`로 생성한 컨텍스트는 여기에서 자동으로 재사용 가능하지 않습니다.

```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은 루트에 식별자를 반환합니다:

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

`resource_id`, `stream_key`, `thread_short_id`와 같은 추가 식별자가 있을 수 있습니다. 성공적인 생성 응답은 작업이 접수되었음을 의미할 뿐, 생성이 완료되었음을 뜻하지는 않습니다. 요청한 슬라이드 수는 지침이며, 청구는 실제 생성된 페이지 수를 사용합니다.

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

### SSE로 생성 이벤트 읽기

생성 시 `stream_key`가 반환되면, 동일 계정의 API Key로 즉시 연결하세요. stream key가 반환되지 않으면 아래의 상태 및 결과 조회를 사용하세요.

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

| 쿼리 매개변수 | 의미 |
|---|---|
| `format` | `raw`(기본값)는 `content` 문자열을 그대로 유지하고, `structured`는 유효한 JSON을 객체 또는 배열로 디코딩합니다 |
| `offset` | 재연결을 위한 상위 재개 위치; 로컬 이벤트 수로 추정하지 마세요 |

각 완전한 SSE 이벤트를 읽고, 외부 JSON을 디코딩한 다음 `content`를 처리하세요. `answer` 애플리케이션 이벤트는 `data.text`에 텍스트를 담고 있으며, `finished`는 스트림에서 생성 완료를 신호합니다. 상위 계층의 `done`, `[DONE]`, `error` 신호도 처리하세요. 완료 신호 없이 연결이 닫히면 작업 상태를 조회하세요.

[SuperAgent SSE](https://openapi.felo.ai/ko/docs/api-reference/superagent.md#2-sse)의 파싱 규칙과 클라이언트 예제를 이 섹션의 `/api/v1/data/conversations/stream/{stream_key}` URL과 함께 사용하세요. 스트림이 끝난 뒤 작업 결과를 읽으세요. PPTX 내보내기는 별도 단계로 남아 있습니다. 이 엔드포인트는 `/api/v1/data/chat`에서 `stream: true`를 활성화하지 않습니다.



## 수명, 소유권 및 청구

- 프레젠테이션은 **생성 후 7일**에 만료됩니다. 조회와 내보내기는 이 기간을 연장하지 않습니다. 프레젠테이션 `expires_at`과 서명된 다운로드 URL `expires_at`은 서로 다른 수명을 나타냅니다.
- 생성한 API 계정만 자신의 작업과 프레젠테이션에 접근할 수 있습니다. 누락되었거나 접근할 수 없는 리소스는 404를 반환할 수 있으며, 만료되었거나 삭제된 리소스는 410을 반환하거나 정리 후 404가 될 수 있습니다.
- 생성은 생성된 페이지당(`ppt.generate`) 과금됩니다. 페이지 가격 책정에서는 생성 시 10페이지 가격을 예약한 다음 실제 성공 출력으로 정산하고 사용되지 않은 예약분을 해제합니다. 프롬프트가 더 적은 페이지를 요청하더라도 계정에는 예약에 충분한 가용 잔액이 있어야 합니다.
- 내보내기는 별도의 요청 가격(`ppt.export`)이 있습니다. 상태 조회, 결과 조회, export-status 조회, 삭제는 새 요금을 발생시키지 않습니다.
- 타임아웃 후에는 새 프레젠테이션을 만들지 말고 저장된 작업을 조회하세요. [청구 및 오류](https://openapi.felo.ai/ko/docs/data-api/guides/felo-billing.md)를 참조하세요.