# PPT 生成とエクスポート

プレゼンテーションを作成し、進行状況をポーリングし、PPTX をエクスポートして、そのライフサイクルを管理します。

プレゼンテーションを非同期で生成し、その後 PPTX ファイルをエクスポートします。生成とエクスポートの手順は分けてください。作成されたタスクはまだ完成したファイルではありません。

すべての例は [概要](https://openapi.felo.ai/ja/docs/data-api/guides/felo-overview.md) の `FELO_API_KEY` を使用します。呼び出しには **プラットフォーム残高** が使われ、Felo Pro クレジットは使われません。レスポンス例は説明用であり、実際の内容や任意フィールドは変動します。

## ワークフローと識別子

1. 生成タスクを作成し、`task_id`、`ppt_business_id`、`expires_at` を保存します。
2. `task_id` を使って生成ステータスをポーリングします。
3. `task_id` を使って生成結果を読み取ります。
4. `ppt_business_id` を使って PPTX エクスポートを開始します。
5. エクスポートステータスをポーリングし、完了したファイルをダウンロードします。
6. 必要に応じて、プレゼンテーションを早期に削除します。

ルートプレースホルダーでは、`{business_id}` は返された **`ppt_business_id`** を意味し、`task_id`、`resource_id`、`livedoc_short_id` ではありません。ワークフロー全体で同じ API アカウントを使用してください。例の ID はプレースホルダーです。

## 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 キーでただちに接続してください。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 イベントを 1 件ずつ読み取り、外側の JSON をデコードしてから `content` を処理してください。`answer` アプリケーションイベントは `data.text` にテキストを持ちます。`finished` はストリーム内での生成完了を示します。上流の `done`、`[DONE]`、`error` シグナルにも対応してください。接続が完了シグナルなしで閉じた場合は、タスクステータスを問い合わせてください。

[SuperAgent SSE](https://openapi.felo.ai/ja/docs/api-reference/superagent.md#2-sse-消費) の解析ルールとクライアント例を、このセクションの `/api/v1/data/conversations/stream/{stream_key}` URL とともに使用してください。ストリーム終了後にタスク結果を読み取ってください。PPTX エクスポートは引き続き別ステップです。このエンドポイントは `/api/v1/data/chat` で `stream: true` を有効にしません。

## 2. 生成ステータスをポーリングする

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

レスポンスにはルートの `status` 文字列があり、たとえば `RUNNING` や `COMPLETED` です。間隔を制限したうえで、たとえば 2〜5 秒ごとに、期限を設定してポーリングしてください。完了後は結果へ進み、成功を前提にせず失敗や想定外のステータスを処理してください。ポーリングの期限はタスクをキャンセルしません。

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

## 3. 生成結果を読み取る

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

これは **POST** であり、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
}
```

`history_data` を使う前に `task_status` を読み取ってください。履歴ペイロードはタスクによって異なり、null の場合があります。`ai_page_html` と `thread_short_id` は任意です。このレスポンスは、PPTX のダウンロード URL が保証されるものではありません。次にエクスポートを使用してください。

## 4. 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}
```

エクスポートする前に生成が完了していなければなりません。同じエクスポートが実行中の場合、POST を繰り返してもそれが再利用されます。完了後に別のエクスポートを開始すると、新しいエクスポートが作成され、追加課金が発生する場合があります。ポーリングとダウンロードリンクの更新には GET を使用してください。

## 5. エクスポートをポーリングしてダウンロードする

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

| ステータス | 次のアクション |
|---|---|
| `NOT_STARTED` | エクスポートを 1 回送信します |
| `PROCESSING` | 待機してから再度 GET でポーリングします |
| `COMPLETED` | `download_url` を読み取り、ファイルをダウンロードします |
| `FAILED` | 新しいエクスポートを送信する前に、エラーとタスク状態を確認します |

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

サンプル URL は説明用です。レスポンスから実際の署名付き URL を使用してください。この URL は **30 分間** 有効です。プレゼンテーションが利用可能な間は、GET のエクスポートステータスで新しいリンクを返すことがあります。ファイルは有効期間内に保存してください。Felo API キーをファイルダウンロードホストに送信しないでください。

## 6. プレゼンテーションを削除する

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

成功時は **HTTP 204 でボディなし** を返します。JSON として解析しないでください。生成中に削除すると 409 が返されます。

## 有効期間、所有権、課金

- プレゼンテーションは **作成から 7 日後** に期限切れになります。クエリやエクスポートではこの期間は延長されません。プレゼンテーションの `expires_at` と署名付きダウンロード URL の `expires_at` は、異なる有効期間を示します。
- 作成した API アカウントのみが、そのタスクとプレゼンテーションにアクセスできます。存在しない、またはアクセスできないリソースは 404 を返す場合があります。期限切れまたは削除済みのリソースは 410、またはクリーンアップ後に 404 を返す場合があります。
- 生成は生成ページごとに課金されます（`ppt.generate`）。ページ単価では、作成時に 10 ページ分の価格が予約され、実際の成功出力で精算され、未使用の予約分は解放されます。プロンプトで要求するページ数が少なくても、アカウントには予約に十分な利用可能残高が必要です。
- エクスポートには別のリクエスト単価（`ppt.export`）があります。ステータス照会、結果照会、エクスポートステータス照会、削除では新しい課金は発生しません。
- タイムアウト後は、別のプレゼンテーションを作成するのではなく、保存済みのタスクを問い合わせてください。[課金とエラー](https://openapi.felo.ai/ja/docs/data-api/guides/felo-billing.md) を参照してください。