# PPT Oluşturma ve Dışa Aktarma

Bir sunum oluşturun, ilerlemesini sorgulayın, bir PPTX dışa aktarın ve yaşam döngüsünü yönetin.

Bir sunumu eşzamansız olarak oluşturun, ardından bir PPTX dosyası dışa aktarın. Oluşturma ve dışa aktarma adımlarını ayrı tutun: oluşturulmuş bir görev henüz bitmiş bir dosya değildir.

Tüm örnekler [genel bakış](https://openapi.felo.ai/tr/docs/data-api/guides/felo-overview.md) içindeki `FELO_API_KEY`’i kullanır. Çağrılar Felo Pro kredilerini değil, **platform bakiyesini** kullanır. Yanıt örnekleri açıklayıcıdır; canlı içerik ve isteğe bağlı alanlar değişebilir.

## İş akışı ve tanımlayıcılar

1. Bir oluşturma görevi oluşturun; `task_id`, `ppt_business_id` ve `expires_at` değerlerini kaydedin.
2. Oluşturma durumunu `task_id` kullanarak sorgulayın.
3. Oluşturma sonuçlarını `task_id` kullanarak okuyun.
4. `ppt_business_id` kullanarak PPTX dışa aktarmayı başlatın.
5. Dışa aktarma durumunu sorgulayın ve tamamlanan dosyayı indirin.
6. İsteğe bağlı olarak sunumu erken silin.

Rota yer tutucularında `{business_id}`, döndürülen **`ppt_business_id`** anlamına gelir; `task_id`, `resource_id` veya `livedoc_short_id` anlamına gelmez. Tüm iş akışı için aynı API hesabını kullanın. Örneklerdeki kimlikler yer tutucudur.

## 1. Sunumu oluşturun

`POST /api/v1/data/ppts`

| Alan | Tür | Gerekli | Anlamı |
|---|---|---|---|
| `query` | string | Evet | Oluşturma yönergeleri, 1–25.000 karakter |
| `stream_protocol` | string | Hayır | Varsayılan `message_center_v1`; normalde değiştirmeden bırakın |
| `ppt_config` | object | Hayır | İsteğe bağlı yapılandırma; mevcut uygulama `ai_theme_id` okur |
| `livedoc_short_id` | string | Hayır | Mevcut bağlam kimliği, en fazla 100 karakter; yerel API sahipliği ve süre dolumu kontrollerinden geçmelidir |
| `resource_ids` | string array | Hayır | En fazla 100 UUID kaynak kimliği; aynı bağlam erişim kontrollerine tabidir |

İlk entegrasyon için bağlam ve yapılandırma alanlarını atlayın. `/v2` üzerinden oluşturulan bir bağlam burada otomatik olarak yeniden kullanım için uygun değildir.

```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, kökte tanımlayıcılar döndürür:

```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` ve `thread_short_id` gibi ek tanımlayıcılar bulunabilir. Başarılı bir oluşturma yanıtı, görevin kabul edildiği anlamına gelir; oluşturmanın tamamlandığı anlamına gelmez. İstenen slayt sayısı bir yönergedir; faturalandırma gerçek oluşturulan sayfa sayısını kullanır.

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

### SSE ile oluşturma olaylarını okuyun

Oluşturma bir `stream_key` döndürürse, aynı hesaba ait bir API Anahtarı ile hemen bağlanın. Herhangi bir stream key döndürülmezse, aşağıdaki durum ve sonuç sorgularını kullanın.

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

| Sorgu parametresi | Anlamı |
|---|---|
| `format` | `raw` (varsayılan) `content` dizesini korur; `structured` geçerli JSON’u bir nesneye veya diziye çözer |
| `offset` | Yeniden bağlanma için isteğe bağlı üst akış devam konumu; bunu yerel olay sayınızdan çıkarsamayın |

Her tamamlanmış SSE olayını okuyun, dıştaki JSON’unu çözün, ardından `content` öğesini işleyin. Bir `answer` uygulama olayı, `data.text` içinde metin taşır; `finished` ise akışta oluşturmanın tamamlandığını belirtir. Ayrıca üst akış `done`, `[DONE]` ve `error` sinyallerini de işleyin. Bağlantı bir tamamlanma sinyali olmadan kapanırsa, görev durumunu sorgulayın.

Ayrıntıları ve istemci örneğini [SuperAgent SSE](https://openapi.felo.ai/tr/docs/api-reference/superagent.md#2-sse-ak-n-t-ket) bölümündeki ayrıştırma kurallarıyla kullanın; bu bölümün `/api/v1/data/conversations/stream/{stream_key}` URL’si için. Akış bittikten sonra görev sonucunu okuyun; PPTX dışa aktarma ayrı bir adımdır. Bu uç nokta `/api/v1/data/chat` üzerinde `stream: true` etkinleştirmez.

## 2. Oluşturma durumunu sorgulayın

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

Yanıtın kökünde, örneğin `RUNNING` veya `COMPLETED` gibi bir `status` dizesi vardır. Sabitlenmiş bir aralıkla (örneğin 2–5 saniye) ve bir son tarih ile sorgulayın. Başarı varsaymadan, tamamlandıktan sonra sonuçlara geçin; başarısızlığı ve beklenmeyen durumları işleyin. Bir sorgulama son tarihi görevi iptal etmez.

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

## 3. Oluşturma sonuçlarını okuyun

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

Bu bir **POST** isteğidir ve JSON gövdesi gerekmez.

```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` kullanmadan önce `task_status` değerini okuyun. Geçmiş yükü göreve göre değişebilir ve null olabilir. `ai_page_html` ve `thread_short_id` isteğe bağlıdır. Bu yanıt, garantili bir PPTX indirme bağlantısı değildir; bunun yerine dışa aktarmayı kullanın.

## 4. PPTX dışa aktarmayı başlatın

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

Dışa aktarmadan önce oluşturmanın tamamlanmış olması gerekir. Aynı dışa aktarma çalışırken POST’u tekrarlamak onu yeniden kullanır. Tamamlanmadan sonra başka bir dışa aktarma başlatmak yeni bir dışa aktarma oluşturur ve başka bir ücrete neden olabilir. İndirme bağlantısını sorgulamak ve yenilemek için GET kullanın.

## 5. Dışa aktarmayı sorgulayın ve indirin

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

| Durum | Sonraki işlem |
|---|---|
| `NOT_STARTED` | Dışa aktarmayı bir kez gönderin |
| `PROCESSING` | Bekleyin, sonra GET ile tekrar sorgulayın |
| `COMPLETED` | `download_url` değerini okuyun ve dosyayı indirin |
| `FAILED` | Yeni bir dışa aktarma göndermeden önce hatayı ve görev durumunu inceleyin |

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

Örnek URL açıklayıcıdır. Yanıttaki gerçek imzalı URL’yi kullanın. Bu URL **30 dakika** geçerlidir; GET dışa aktarma durumu, sunum kullanılabilir olduğu sürece yeni bir bağlantı döndürebilir. Dosyayı bu süre içinde kaydedin. Felo API anahtarınızı dosya indirme ana bilgisayarına göndermeyin.

## 6. Sunumu silin

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

Başarı **gövdesiz HTTP 204** döndürür. Bunu JSON olarak ayrıştırmayın. Oluşturma sürerken silme işlemi 409 döndürür.

## Yaşam süresi, sahiplik ve faturalandırma

- Sunumların süresi **oluşturulmadan yedi gün sonra** dolar. Sorgular ve dışa aktarmalar bu süreyi uzatmaz. Sunum `expires_at` değeri ile imzalı indirme URL’sinin `expires_at` değeri farklı ömürleri tanımlar.
- Yalnızca oluşturan API hesabı kendi görevlerine ve sunumlarına erişebilir. Eksik veya erişilemeyen bir kaynak 404 döndürebilir; süresi dolmuş veya silinmiş bir kaynak 410, ya da temizlemeden sonra 404 döndürebilir.
- Oluşturma, oluşturulan sayfa başına (`ppt.generate`) faturalandırılır. Sayfa fiyatlandırmasında, oluşturma on sayfanın fiyatını ayırır, ardından gerçek başarılı çıktıyla kesinleşir ve kullanılmayan rezervasyonu serbest bırakır. İstem daha az sayfa istese bile hesabınızın bu rezervasyon için yeterli kullanılabilir bakiyesi olmalıdır.
- Dışa aktarma ayrı bir istek fiyatına sahiptir (`ppt.export`). Durum sorguları, sonuç sorguları, dışa aktarma-durumu sorguları ve silme yeni bir ücret oluşturmaz.
- Zaman aşımından sonra başka bir sunum oluşturmak yerine kaydedilmiş görevi sorgulayın. [Faturalandırma ve Hatalar](https://openapi.felo.ai/tr/docs/data-api/guides/felo-billing.md) bölümüne bakın.