# Dosya yükleme

Dosyayı bir kez yükleyin, ardından Messages, Responses, görsel üretimi ve video üretimi isteklerinde ID ile başvurun.

Bir dosyayı bir kez yükleyin, ardından model isteklerinde ona ID'siyle başvurun. Bu, aynı baytları base64 olarak yeniden göndermenin veya dosyayı herkese açık bir URL'de barındırmanın yerini alır.

Dosya ID'si Messages, Responses, görsel oluşturma ve video oluşturma ile çalışır. Chat Completions ile çalışmaz.

## Başlamadan önce

- Bir API anahtarı. Bkz. [Kimlik Doğrulama](https://openapi.felo.ai/tr/docs/authentication.md).
- `https://openapi.felo.ai` temel URL'si.
- Göndermeyi planladığınız dosya türünü kabul eden bir model. Bkz. [Model desteğini kontrol etme](#model-deste-ini-kontrol-etme).

## Hızlı başlangıç

### 1. Dosyayı yükleme

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

Başarılı bir yükleme, dosyanın meta verileriyle birlikte HTTP `200` döndürür:

```json
{
  "id": "felo_file_0179...",
  "type": "file",
  "source": "upload",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 482113,
  "created_at": "2026-11-10T02:25:41Z",
  "downloadable": false
}
```

`id` değerini saklayın. Onu opak bir dize olarak ele alın: kendiniz oluşturmayın veya ayrıştırmayın.

### 2. Dosyaya bir istekte başvurma

```bash
curl "https://openapi.felo.ai/api/v1/responses" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_file", "file_id": "felo_file_0179..."},
          {"type": "input_text", "text": "Summarize the attached report."}
        ]
      }
    ]
  }'
```

Aynı iki adım Python ile:

```python
import os

import requests

BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}


def upload(path: str) -> str:
    with open(path, "rb") as file:
        response = requests.post(
            f"{BASE}/api/v1/files",
            headers=HEADERS,
            files={"file": file},
            timeout=300,
        )
    response.raise_for_status()
    return response.json()["id"]


file_id = upload("./report.pdf")

response = requests.post(
    f"{BASE}/api/v1/responses",
    headers=HEADERS,
    json={
        "model": "gpt-5.5",
        "input": [
            {
                "role": "user",
                "content": [
                    {"type": "input_file", "file_id": file_id},
                    {"type": "input_text", "text": "Summarize the attached report."},
                ],
            }
        ],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

Node.js 20 veya üzeri ile:

```javascript
import { openAsBlob } from "node:fs";
import { basename } from "node:path";

const BASE = "https://openapi.felo.ai";
const headers = { Authorization: `Bearer ${process.env.FELO_API_KEY}` };

async function upload(path) {
  const form = new FormData();
  form.append("file", await openAsBlob(path), basename(path));
  const response = await fetch(`${BASE}/api/v1/files`, { method: "POST", headers, body: form });
  if (!response.ok) throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
  return (await response.json()).id;
}

const fileId = await upload("./report.pdf");
```

### Yükleme kuralları

- Gövde, `file` adlı tam olarak bir parça içeren `multipart/form-data` biçimindedir. `purpose` dahil başka herhangi bir parça `invalid_file` ile reddedilir.
- `Content-Type` başlığını HTTP istemcinizin ayarlamasına izin verin. Elle ayarlamak multipart boundary değerinin kaybolmasına yol açar.
- Yükleme URL'sine sorgu parametreleri eklemeyin.
- Bir SDK'nın Files yardımcısı yerine HTTP üzerinden yükleyin. OpenAI SDK'sının `files.create()` yöntemi her zaman `purpose` gönderir, bu nedenle bu endpoint'i çağıramaz.
- Zaman aşımına uğrayan veya bağlantısı kopan bir yükleme yine de depolanmış olabilir. Yeniden yüklemeden önce dosyalarınızı listeleyin.

## Dosya ID'si nerede kullanılabilir

| Endpoint | Dosya türleri | Gerekli giriş modalitesi | Alan |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, görsel | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, görsel | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Görsel | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Görsel | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Görsel, MP4, ses | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Desteklenmiyor | | |

### Messages

```json
{
  "model": "claude-haiku-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "felo_file_0179..."}},
        {"type": "text", "text": "Summarize the attached report."}
      ]
    }
  ]
}
```

Görsel için `{"type": "image", "source": {"type": "file", "file_id": "..."}}` kullanın.

### Responses

| Dosya | İçerik bloğu |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Görsel | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

`file_id` taşıyan bir blok ayrıca URL veya base64 verisi taşımamalıdır.

### Görsel oluşturma

```json
{
  "model": "gemini-3-pro-image",
  "prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_0179..."}}
  ]
}
```

İsteğin geri kalanı, `202` yanıtı ve yoklama [Görsel Oluşturma](https://openapi.felo.ai/tr/docs/guides/image-generation.md) sayfasında açıklanmıştır.

### Video oluşturma

İlk ve son kareler `frame_images` içinde yer alır:

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "The camera slowly pushes in. Keep the colors and composition.",
  "duration": 5,
  "resolution": "720p",
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {"file_id": "felo_file_0179..."}
    }
  ]
}
```

Bitiş karesi için `"frame_type": "last_frame"` içeren ikinci bir girdi ekleyin. Son kare, bir ilk kare gerektirir.

Referans materyali `input_references` içinde yer alır. Her girdi, kendi medya türüyle eşleşen konum belirleyiciyi kullanır:

```json
{
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_IMAGE"}},
    {"type": "video_url", "video_url": {"file_id": "felo_file_VIDEO"}},
    {"type": "audio_url", "audio_url": {"file_id": "felo_file_AUDIO"}}
  ]
}
```

Bir modelin hangi kombinasyonları kabul ettiği modele ve kanala bağlıdır. `frame_images` ve `input_references` aynı istekte kullanılamaz.

### Konum belirleyici kuralları

- Görsel ve video isteklerinde her `image_url`, `video_url` veya `audio_url` nesnesi `file_id` veya `url` alanlarından tam olarak birini içerir ve başka alan içermez.
- Tek bir dizide `file_id` kullanan girdilerle `url` kullanan girdiler bir arada bulunabilir.
- Görsel ve video oluşturma yalnızca sizin yüklediğiniz dosyaları kabul eder. Oluşturulmuş bir görseli yeniden kullanmak için çıktı `url` değerini geçirin.
- Bir dosyaya başvuran istek, hata durumunda başka bir kanala taşınmaz. Hatayı kontrol etmeden farklı bir kanalda yeniden denemeyin.
- Bir dosyayı, ona başvuran tüm görevler nihai bir duruma ulaşana kadar saklayın. Daha önce silmek görevin başarısız olmasına yol açabilir.

## Model desteğini kontrol etme

Depolanan bir dosya her modelle otomatik olarak kullanılamaz. Model, eşleşen giriş modalitesini herkese açık katalogda bildirmelidir:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| Gönderilecek | `input_modalities` şunu içermelidir |
|---|---|
| PDF | `file` |
| Görsel | `image` |
| MP4 | `video` |
| Ses dosyası | `audio` |

Boş veya eksik bir liste, o model için dosya ID'lerinin etkin olmadığı anlamına gelir. Bu durumda istek `file_model_unsupported` ile başarısız olur. Destek olup olmadığını model adından çıkarsamayın.

## Sınırlar

| Sınır | Değer |
|---|---|
| Yükleme boyutu | Dosya başına 100 MiB (104,857,600 bayt); boş dosyalar reddedilir |
| Model isteği başına başvurulan bayt | Toplam 50,000,000 bayt |
| Model isteği başına referans | 100 |
| Dosya adı uzunluğu | 255 karakter |

Aynı dosyaya iki kez başvurmak, her iki istek sınırı için de iki kez sayılır. 50 MB ile 100 MiB arasındaki bir dosya yüklenebilir ancak bir model isteğinde ona başvurulamaz. Bir model veya kanal daha düşük bir sınır uygulayabilir.

### Dosya türleri

Tür, dosyanın uzantısından veya parçanın `Content-Type` değerinden değil, dosyanın içeriğinden algılanır.

| Tür | Biçimler | Başvurulabileceği yerler |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Görsel | PNG, JPEG, GIF, WebP | Messages, Responses, görsel oluşturma, video oluşturma |
| Video | MP4 | Video oluşturma |
| Ses | MP3, WAV, FLAC, OGG | Video oluşturma |
| Office | DOCX, XLSX, PPTX | Yalnızca depolama |
| Metin | `text/plain` olarak depolanan UTF-8 metin | Yalnızca depolama |

Diğer tüm içerikler `invalid_file` ile reddedilir.

### Dosya adları

Dosya adı `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` veya kontrol karakterleri içeremez. `/` ayırıcı olarak kullanılabilir, ancak boş bölümlere, `.` ve `..` kullanımına izin verilmez.

## Dosyaları yönetme

Dosyalar hesabınıza aittir. Hesaptaki her API anahtarı aynı dosyaları görür; diğer hesaplar dosya ID'lerinizi kullanamaz.

### Dosyaları listeleme

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "data": [
    {
      "id": "felo_file_0179...",
      "type": "file",
      "source": "upload",
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 482113,
      "created_at": "2026-11-10T02:25:41Z",
      "downloadable": false
    }
  ],
  "first_id": "felo_file_0179...",
  "last_id": "felo_file_0179...",
  "cursor": "felo_file_0179...",
  "has_more": false
}
```

Sonuçlar en eskiden en yeniye doğru sıralanır. `has_more` değeri `true` olduğunda, sonraki sayfayı almak için dönen `cursor` değerini geçirin. Sunucu tarafında arama veya tür filtresi yoktur.

### Tek bir dosyayı alma

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### Dosya silme

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"id": "felo_file_0179...", "type": "file_deleted"}
```

Silme hemen geçerli olur ve geri alınamaz. `503`, silmenin tamamlanmadığı anlamına gelir; `DELETE` isteğini yeniden gönderin.

### İndirmeler

Yüklenen dosyalar indirilemez. `GET /api/v1/files/{file_id}/content`, `400 file_not_downloadable` döndürür ve yükleme yanıtının `Location` başlığı dosyanın baytlarını değil, meta verilerini gösterir. Yüklediğiniz her şeyin bir kopyasını kendinizde saklayın.

Oluşturulan medyayı indirmek için görevin `outputs` alanındaki imzalı URL'leri kullanın.

## API referansı

Tüm endpoint'ler `Authorization: Bearer YOUR_API_KEY` kullanır. Başarılı yanıtlar, zarf içermeyen düz JSON nesneleridir.

| Yöntem | Yol | Döndürdüğü |
|---|---|---|
| `POST` | `/api/v1/files` | [Dosya nesnesi](#dosya-nesnesi) |
| `GET` | `/api/v1/files` | [Dosya sayfası](#liste-parametreleri) |
| `GET` | `/api/v1/files/{file_id}` | [Dosya nesnesi](#dosya-nesnesi) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` ve tek dosyalık `GET`, her sorgu parametresini `invalid_query` ile reddeder.

### Dosya nesnesi

| Alan | Tür | Açıklama |
|---|---|---|
| `id` | string | `felo_file_` ön ekli dosya ID'si. `file_id` olarak kullanın |
| `type` | string | Her zaman `file` |
| `source` | string | Yüklediğiniz dosyalar için `upload`, model çıktıları için `generated` |
| `filename` | string | Yüklemeyle birlikte gönderilen ad |
| `mime_type` | string | İçerikten algılanan tür |
| `size_bytes` | integer | Bayt cinsinden boyut |
| `created_at` | string | ISO 8601 UTC zaman damgası |
| `downloadable` | boolean | Yüklenen dosyalar için `false` |

### Yükleme isteği

| Parça | Gerekli | Açıklama |
|---|---|---|
| `file` | Evet | Dosya adıyla birlikte `multipart/form-data` dosya parçası olarak gönderilen dosya |

Yanıt, dosyanın meta verilerinin URL'sini taşıyan bir `Location` başlığı içerir.

### Liste parametreleri

| Parametre | Varsayılan | Açıklama |
|---|---|---|
| `limit` | `100` | Sayfa boyutu, 1 ile 1000 arasında |
| `cursor` | | Önceki sayfadan gelen `cursor` değeri |
| `after`, `after_id` | | `cursor` için takma adlar. Üçünden yalnızca birini gönderin |
| `order` | `asc` | Yalnızca `asc` desteklenir |

| Yanıt alanı | Tür | Açıklama |
|---|---|---|
| `data` | array | Dosya nesneleri, en eskisi önce |
| `first_id` | string veya null | Sayfadaki ilk dosyanın ID'si |
| `last_id` | string veya null | Sayfadaki son dosyanın ID'si |
| `cursor` | string veya null | Sonraki sayfa için `cursor` olarak geçirilecek değer |
| `has_more` | boolean | Başka bir sayfa olup olmadığı |

## Hatalar

Files endpoint'leri, Responses ile görsel ve video oluşturma OpenAI hata zarfını kullanır:

```json
{
  "error": {
    "message": "This model does not accept this attachment type",
    "type": "invalid_request_error",
    "param": "frame_images.0.image_url",
    "code": "file_model_unsupported"
  }
}
```

Files endpoint'lerinden gelen hatalarda `param` değeri `null` olur. Messages, `error.code` içermeyen Anthropic hata biçimini döndürür. İstek ID'si `X-Request-Id` yanıt başlığındadır.

Dosya yüklerken veya yönetirken oluşan hatalar:

| HTTP | `error.code` | Anlamı |
|---|---|---|
| 400 | `invalid_content_type` | Gövde `multipart/form-data` değil |
| 400 | `invalid_file` | `file` parçası yok, fazladan bir parça var, dosya boş veya içerik desteklenmiyor |
| 400 | `invalid_filename` | Dosya adı çok uzun veya reddedilen bir karakter içeriyor |
| 413 | `file_too_large` | Dosya 100 MiB sınırını aşıyor |
| 400 | `invalid_query` | Desteklenmeyen bir sorgu parametresi veya `asc` dışında bir `order` değeri |
| 400 | `invalid_limit` | `limit` 1 ile 1000 aralığının dışında |
| 400 | `invalid_cursor` | İmleç hatalı biçimlendirilmiş veya birden fazla imleç gönderildi |
| 400 | `file_not_downloadable` | `/content` istendi |
| 404 | `file_not_found` | Dosya mevcut değil, silinmiş veya başka bir hesaba ait |
| 503 | `file_storage_unavailable` | Dosya depolama geçici olarak kullanılamıyor; daha sonra yeniden deneyin |
| 503 | `file_upload_expired` | Yükleme zamanında tamamlanmadı; dosyayı yeniden yükleyin |

Bir model isteğinde dosyaya başvururken oluşan hatalar:

| HTTP | `error.code` | Anlamı |
|---|---|---|
| 400 | `invalid_file_input` | Hatalı biçimlendirilmiş ID, tek bir konum belirleyicide hem `file_id` hem `url` veya 100'den fazla referans |
| 400 | `unsupported_file_type` | Dosyanın türü konumla eşleşmiyor, örneğin belge bloğunda bir MP4 |
| 400 | `file_model_unsupported` | Model gerekli giriş modalitesini bildirmiyor |
| 400 | `file_input_too_large` | Başvurulan dosyalar toplamda 50,000,000 baytı aşıyor |
| 400 | `file_protocol_unsupported` | Chat Completions'a bir dosya ID'si gönderildi |
| 404 | `file_not_found` | Dosya mevcut değil, silinmiş, başka bir hesaba ait veya görsel ya da video oluşturmaya gönderilen oluşturulmuş bir dosya |

Görsel ve video oluşturmada bir dosya `202` yanıtından sonra da başarısız olabilir. Bu durumda görev, `error.code` içinde bu kodlardan biriyle `failed` olarak sona erer.

Kimlik doğrulama, bakiye ve hız sınırı hataları [Hatalar, Sınırlar ve Yeniden Denemeler](https://openapi.felo.ai/tr/docs/guides/errors-and-limits.md) bölümünde açıklanmıştır.

## İlgili

- [Protokoller ve SDK’lar](https://openapi.felo.ai/tr/docs/guides/protocols.md)
- [Görsel Oluşturma](https://openapi.felo.ai/tr/docs/guides/image-generation.md)
- [Eşzamansız Görevler](https://openapi.felo.ai/tr/docs/guides/async-tasks.md)
- [Model API referansı](https://openapi.felo.ai/tr/docs/model-api)
