# Przesyłanie plików

Prześlij plik raz, a potem odwołuj się do niego przez ID w żądaniach Messages, Responses, generowania obrazów i wideo.

Prześlij plik raz, a potem odwołuj się do niego przez ID w żądaniach do modeli. Zastępuje to ponowne wysyłanie tych samych bajtów jako base64 albo hostowanie pliku pod publicznym adresem URL.

ID pliku działa z Messages, Responses, generowaniem obrazów i generowaniem wideo. Nie działa z Chat Completions.

## Zanim zaczniesz

- Klucz API. Zobacz [Uwierzytelnianie](https://openapi.felo.ai/pl/docs/authentication.md).
- Bazowy adres URL `https://openapi.felo.ai`.
- Model, który akceptuje typ pliku, jaki zamierzasz wysłać. Zobacz [Sprawdzanie obsługi przez model](#sprawdzanie-obs-ugi-przez-model).

## Szybki start

### 1. Przesłanie pliku

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

Skuteczne przesłanie zwraca HTTP `200` z metadanymi pliku:

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

Zapisz `id`. Traktuj tę wartość jako nieprzezroczysty ciąg znaków: nie buduj jej ani nie parsuj.

### 2. Odwołanie do pliku w żądaniu

```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."}
        ]
      }
    ]
  }'
```

Te same dwa kroki w Pythonie:

```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())
```

I w Node.js 20 lub nowszym:

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

### Zasady przesyłania

- Treść to `multipart/form-data` z dokładnie jedną częścią o nazwie `file`. Każda inna część, w tym `purpose`, jest odrzucana z kodem `invalid_file`.
- Pozwól klientowi HTTP ustawić `Content-Type`. Ręczne ustawienie powoduje utratę multipart boundary.
- Nie dodawaj parametrów zapytania do adresu URL przesyłania.
- Przesyłaj przez HTTP zamiast przez helper Files z SDK. Metoda `files.create()` z SDK OpenAI zawsze wysyła `purpose`, więc nie może wywołać tego endpointu.
- Przesyłanie, które przekroczyło limit czasu lub zostało przerwane przez rozłączenie, mogło mimo to zostać zapisane. Zanim prześlesz plik ponownie, wyświetl listę swoich plików.

## Gdzie można użyć ID pliku

| Endpoint | Typy plików | Wymagana modalność wejściowa | Pole |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, obraz | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, obraz | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Obraz | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Obraz | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Obraz, MP4, audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Nieobsługiwane | | |

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

Dla obrazu użyj `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Plik | Blok treści |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Obraz | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Blok zawierający `file_id` nie może jednocześnie zawierać adresu URL ani danych base64.

### Generowanie obrazów

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

Pozostałą część żądania, odpowiedź `202` i odpytywanie opisuje strona [Generowanie obrazów](https://openapi.felo.ai/pl/docs/guides/image-generation.md).

### Generowanie wideo

Pierwsza i ostatnia klatka trafiają do `frame_images`:

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

Aby ustawić klatkę końcową, dodaj drugi wpis z `"frame_type": "last_frame"`. Ostatnia klatka wymaga pierwszej klatki.

Materiały referencyjne trafiają do `input_references`. Każdy wpis używa lokatora odpowiadającego jego typowi mediów:

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

To, które kombinacje model akceptuje, zależy od modelu i kanału. Pól `frame_images` i `input_references` nie można używać w tym samym żądaniu.

### Zasady dotyczące lokatorów

- W żądaniach dotyczących obrazów i wideo każdy obiekt `image_url`, `video_url` lub `audio_url` zawiera dokładnie jedno z pól `file_id` albo `url` i żadnego innego pola.
- Jedna tablica może łączyć wpisy używające `file_id` z wpisami używającymi `url`.
- Generowanie obrazów i wideo akceptuje tylko pliki przesłane przez Ciebie. Aby ponownie użyć wygenerowanego obrazu, przekaż jego wyjściowy `url`.
- Żądanie, które odwołuje się do pliku, nie jest w razie niepowodzenia przenoszone na inny kanał. Nie ponawiaj go na innym kanale bez sprawdzenia błędu.
- Zachowaj plik, dopóki każde zadanie, które się do niego odwołuje, nie osiągnie stanu terminalnego. Wcześniejsze usunięcie może spowodować niepowodzenie zadania.

## Sprawdzanie obsługi przez model

Zapisany plik nie nadaje się automatycznie do użycia z każdym modelem. Model musi deklarować odpowiednią modalność wejściową w publicznym katalogu:

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

| Co wysyłasz | `input_modalities` musi zawierać |
|---|---|
| PDF | `file` |
| Obraz | `image` |
| An MP4 | `video` |
| Plik audio | `audio` |

Pusta lub brakująca lista oznacza, że ID plików nie są włączone dla tego modelu. Żądanie kończy się wtedy błędem `file_model_unsupported`. Nie wnioskuj o obsłudze z nazwy modelu.

## Limity

| Limit | Wartość |
|---|---|
| Rozmiar przesyłanego pliku | 100 MiB (104,857,600 bajtów) na plik; puste pliki są odrzucane |
| Rozmiar plików, do których odwołuje się jedno żądanie do modelu | łącznie 50,000,000 bajtów |
| Liczba odwołań w jednym żądaniu do modelu | 100 |
| Długość nazwy pliku | 255 znaków |

Dwukrotne odwołanie do tego samego pliku liczy się dwa razy do obu limitów żądania. Plik o rozmiarze od 50 MB do 100 MiB można przesłać, ale nie można się do niego odwołać w żądaniu do modelu. Model lub kanał może stosować niższy limit.

### Typy plików

Typ jest wykrywany na podstawie zawartości pliku, a nie jego rozszerzenia ani `Content-Type` części.

| Typ | Formaty | Gdzie można się odwołać |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Obraz | PNG, JPEG, GIF, WebP | Messages, Responses, generowanie obrazów, generowanie wideo |
| Wideo | MP4 | Generowanie wideo |
| Audio | MP3, WAV, FLAC, OGG | Generowanie wideo |
| Office | DOCX, XLSX, PPTX | Tylko przechowywanie |
| Tekst | Tekst UTF-8, zapisywany jako `text/plain` | Tylko przechowywanie |

Każda inna zawartość jest odrzucana z kodem `invalid_file`.

### Nazwy plików

Nazwa pliku nie może zawierać `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` ani znaków sterujących. `/` jest dozwolony jako separator, ale puste segmenty, `.` i `..` już nie.

## Zarządzanie plikami

Pliki należą do Twojego konta. Każdy klucz API na koncie widzi te same pliki; inne konta nie mogą używać Twoich ID plików.

### Wyświetlanie listy plików

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

Wyniki są uporządkowane od najstarszych. Gdy `has_more` ma wartość `true`, przekaż zwrócony `cursor`, aby pobrać następną stronę. Nie ma wyszukiwania ani filtra typu po stronie serwera.

### Odczyt jednego pliku

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

### Usuwanie pliku

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

Usunięcie działa natychmiast i nie można go cofnąć. `503` oznacza, że usuwanie się nie zakończyło; wyślij `DELETE` ponownie.

### Pobieranie

Przesłanych plików nie można pobrać. `GET /api/v1/files/{file_id}/content` zwraca `400 file_not_downloadable`, a nagłówek `Location` w odpowiedzi na przesłanie wskazuje metadane pliku, a nie jego bajty. Zachowaj własną kopię wszystkiego, co przesyłasz.

Aby pobrać wygenerowane multimedia, użyj podpisanych adresów URL z `outputs` zadania.

## Dokumentacja API

Wszystkie endpointy używają `Authorization: Bearer YOUR_API_KEY`. Udane odpowiedzi to zwykłe obiekty JSON bez koperty.

| Metoda | Ścieżka | Zwraca |
|---|---|---|
| `POST` | `/api/v1/files` | [Obiekt pliku](#obiekt-pliku) |
| `GET` | `/api/v1/files` | [Strona plików](#parametry-listy) |
| `GET` | `/api/v1/files/{file_id}` | [Obiekt pliku](#obiekt-pliku) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` i `GET` pojedynczego pliku odrzucają każdy parametr zapytania z kodem `invalid_query`.

### Obiekt pliku

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | ID pliku z prefiksem `felo_file_`. Używaj go jako `file_id` |
| `type` | string | Zawsze `file` |
| `source` | string | `upload` dla plików przesłanych przez Ciebie, `generated` dla wyników modelu |
| `filename` | string | Nazwa wysłana przy przesyłaniu |
| `mime_type` | string | Typ wykryty na podstawie zawartości |
| `size_bytes` | integer | Rozmiar w bajtach |
| `created_at` | string | Znacznik czasu ISO 8601 w UTC |
| `downloadable` | boolean | `false` dla przesłanych plików |

### Żądanie przesłania

| Część | Wymagane | Opis |
|---|---|---|
| `file` | Tak | Plik wysłany jako część plikowa `multipart/form-data` z nazwą pliku |

Odpowiedź zawiera nagłówek `Location` z adresem URL metadanych pliku.

### Parametry listy

| Parametr | Domyślnie | Opis |
|---|---|---|
| `limit` | `100` | Rozmiar strony, od 1 do 1000 |
| `cursor` | | Wartość `cursor` z poprzedniej strony |
| `after`, `after_id` | | Aliasy `cursor`. Wyślij tylko jeden z tych trzech |
| `order` | `asc` | Obsługiwane jest tylko `asc` |

| Pole odpowiedzi | Typ | Opis |
|---|---|---|
| `data` | array | Obiekty plików, od najstarszych |
| `first_id` | string lub null | ID pierwszego pliku na stronie |
| `last_id` | string lub null | ID ostatniego pliku na stronie |
| `cursor` | string lub null | Wartość do przekazania jako `cursor` dla następnej strony |
| `has_more` | boolean | Czy istnieje kolejna strona |

## Błędy

Endpointy Files, Responses oraz generowanie obrazów i wideo używają koperty błędów OpenAI:

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

Dla błędów z endpointów Files `param` ma wartość `null`. Messages zwraca format błędów Anthropic, który nie ma `error.code`. ID żądania znajduje się w nagłówku odpowiedzi `X-Request-Id`.

Błędy przy przesyłaniu plików i zarządzaniu nimi:

| HTTP | `error.code` | Znaczenie |
|---|---|---|
| 400 | `invalid_content_type` | Treść nie jest `multipart/form-data` |
| 400 | `invalid_file` | Brak części `file`, dodatkowa część, pusty plik lub nieobsługiwana zawartość |
| 400 | `invalid_filename` | Nazwa pliku jest za długa lub zawiera niedozwolony znak |
| 413 | `file_too_large` | Plik przekracza 100 MiB |
| 400 | `invalid_query` | Nieobsługiwany parametr zapytania lub `order` inne niż `asc` |
| 400 | `invalid_limit` | `limit` jest poza zakresem od 1 do 1000 |
| 400 | `invalid_cursor` | Kursor jest nieprawidłowy lub wysłano więcej niż jeden kursor |
| 400 | `file_not_downloadable` | Zażądano `/content` |
| 404 | `file_not_found` | Plik nie istnieje, został usunięty lub należy do innego konta |
| 503 | `file_storage_unavailable` | Magazyn plików jest tymczasowo niedostępny; ponów później |
| 503 | `file_upload_expired` | Przesyłanie nie zakończyło się na czas; prześlij plik ponownie |

Błędy przy odwoływaniu się do pliku w żądaniu do modelu:

| HTTP | `error.code` | Znaczenie |
|---|---|---|
| 400 | `invalid_file_input` | Nieprawidłowy format ID, `file_id` i `url` w jednym lokatorze lub ponad 100 odwołań |
| 400 | `unsupported_file_type` | Typ pliku nie pasuje do pozycji, na przykład MP4 w bloku dokumentu |
| 400 | `file_model_unsupported` | Model nie deklaruje wymaganej modalności wejściowej |
| 400 | `file_input_too_large` | Pliki, do których odwołuje się żądanie, przekraczają łącznie 50,000,000 bajtów |
| 400 | `file_protocol_unsupported` | ID pliku wysłano do Chat Completions |
| 404 | `file_not_found` | Plik nie istnieje, został usunięty, należy do innego konta albo jest wygenerowanym plikiem wysłanym do generowania obrazów lub wideo |

Przy generowaniu obrazów i wideo błąd związany z plikiem może wystąpić także po `202`. Zadanie kończy się wtedy stanem `failed` z jednym z tych kodów w `error.code`.

Błędy uwierzytelniania, salda i limitów szybkości opisuje strona [Błędy, limity i ponawianie](https://openapi.felo.ai/pl/docs/guides/errors-and-limits.md).

## Powiązane

- [Protokoły i SDK](https://openapi.felo.ai/pl/docs/guides/protocols.md)
- [Generowanie obrazów](https://openapi.felo.ai/pl/docs/guides/image-generation.md)
- [Zadania asynchroniczne](https://openapi.felo.ai/pl/docs/guides/async-tasks.md)
- [Dokumentacja Model API](https://openapi.felo.ai/pl/docs/model-api)
