# Nahrávání souborů

Nahrajte soubor jednou a pak na něj odkazujte pomocí ID v požadavcích Messages, Responses, generování obrázků a videa.

Nahrajte soubor jednou a pak na něj v požadavcích na modely odkazujte pomocí ID. Nahrazuje to opakované posílání stejných bajtů v base64 nebo hostování souboru na veřejné URL.

ID souboru funguje s Messages, Responses, generováním obrázků a generováním videa. S Chat Completions nefunguje.

## Než začnete

- API klíč. Viz [Ověřování](https://openapi.felo.ai/cs/docs/authentication.md).
- Základní URL `https://openapi.felo.ai`.
- Model přijímající typ souboru, který chcete odeslat. Viz [Ověřte podporu modelu](#ov-te-podporu-modelu).

## Rychlý start

### 1. Nahrajte soubor

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

Úspěšné nahrání vrací HTTP `200` s metadaty souboru:

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

Uložte si `id`. Zacházejte s ním jako s neprůhledným řetězcem: nesestavujte jej ani neparsujte.

### 2. Odkažte na něj v požadavku

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

Stejné dva kroky v Pythonu:

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

A v Node.js 20 nebo novějším:

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

### Pravidla nahrávání

- Tělo je `multipart/form-data` s právě jednou částí pojmenovanou `file`. Jakákoli jiná část, včetně `purpose`, je odmítnuta s `invalid_file`.
- Nastavení `Content-Type` nechte na svém HTTP klientovi. Při ručním nastavení se ztratí multipart boundary.
- K URL pro nahrávání nepřidávejte parametry dotazu.
- Nahrávejte přes HTTP, nikoli pomocí helperu Files v SDK. `files.create()` v OpenAI SDK vždy posílá `purpose`, takže tento endpoint volat nemůže.
- Nahrání, kterému vypršel časový limit nebo se přerušilo spojení, se přesto mohlo uložit. Před dalším nahráním si vypište své soubory.

## Kde lze ID souboru použít

| Endpoint | Typy souborů | Požadovaná vstupní modalita | Pole |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, obrázek | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, obrázek | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Obrázek | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Obrázek | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Obrázek, MP4, audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Nepodporováno | | |

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

Pro obrázek použijte `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Soubor | Blok obsahu |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Obrázek | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Blok, který obsahuje `file_id`, nesmí zároveň obsahovat URL ani data base64.

### Generování obrázků

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

Zbytek požadavku, odpověď `202` a dotazování jsou popsány v části [Generování obrázků](https://openapi.felo.ai/cs/docs/guides/image-generation.md).

### Generování videa

První a poslední snímek patří 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..."}
    }
  ]
}
```

Pro koncový snímek přidejte druhou položku s `"frame_type": "last_frame"`. Poslední snímek vyžaduje první snímek.

Referenční materiál patří do `input_references`. Každá položka používá lokátor odpovídající jejímu typu média:

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

Které kombinace model přijímá, závisí na modelu a kanálu. `frame_images` a `input_references` nelze použít ve stejném požadavku.

### Pravidla pro lokátory

- V požadavcích na obrázky a video obsahuje každý objekt `image_url`, `video_url` nebo `audio_url` právě jedno z polí `file_id` nebo `url` a žádné další pole.
- V jednom poli lze kombinovat položky s `file_id` a položky s `url`.
- Generování obrázků a videa přijímá pouze soubory, které jste nahráli vy. Chcete-li znovu použít vygenerovaný obrázek, předejte jeho výstupní `url`.
- Požadavek, který odkazuje na soubor, se při selhání nepřesouvá na jiný kanál. Neopakujte jej na jiném kanálu, aniž byste zkontrolovali chybu.
- Soubor si ponechte, dokud každá úloha, která na něj odkazuje, nedosáhne koncového stavu. Dřívější smazání může způsobit selhání úlohy.

## Ověřte podporu modelu

Uložený soubor není automaticky použitelný s každým modelem. Model musí ve veřejném katalogu deklarovat odpovídající vstupní modalitu:

```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 odesíláte | `input_modalities` musí obsahovat |
|---|---|
| PDF | `file` |
| Obrázek | `image` |
| An MP4 | `video` |
| Audio soubor | `audio` |

Prázdný nebo chybějící seznam znamená, že ID souborů nejsou pro daný model povolena. Požadavek pak selže s `file_model_unsupported`. Podporu neodvozujte z názvu modelu.

## Limity

| Limit | Hodnota |
|---|---|
| Velikost nahrávaného souboru | 100 MiB (104,857,600 bajtů) na soubor; prázdné soubory jsou odmítnuty |
| Velikost odkazovaných souborů na jeden požadavek na model | celkem 50,000,000 bajtů |
| Počet odkazů na jeden požadavek na model | 100 |
| Délka názvu souboru | 255 znaků |

Dvojí odkaz na stejný soubor se do obou limitů požadavku počítá dvakrát. Soubor o velikosti mezi 50 MB a 100 MiB lze nahrát, ale nelze na něj odkázat v požadavku na model. Model nebo kanál může uplatnit nižší limit.

### Typy souborů

Typ se zjišťuje z obsahu souboru, nikoli z jeho přípony nebo z `Content-Type` části.

| Typ | Formáty | Kde na něj lze odkázat |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Obrázek | PNG, JPEG, GIF, WebP | Messages, Responses, generování obrázků, generování videa |
| Video | MP4 | Generování videa |
| Audio | MP3, WAV, FLAC, OGG | Generování videa |
| Office | DOCX, XLSX, PPTX | Pouze uložení |
| Text | Text v UTF-8, uložený jako `text/plain` | Pouze uložení |

Jakýkoli jiný obsah je odmítnut s `invalid_file`.

### Názvy souborů

Název souboru nesmí obsahovat `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` ani řídicí znaky. `/` je povoleno jako oddělovač, ale prázdné segmenty, `.` a `..` nikoli.

## Správa souborů

Soubory patří vašemu účtu. Každý API klíč v účtu vidí stejné soubory; jiné účty vaše ID souborů použít nemohou.

### Vypište soubory

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

Výsledky jsou seřazeny od nejstarších. Když je `has_more` rovno `true`, předejte vrácený `cursor` a získáte další stránku. Vyhledávání ani filtr podle typu na straně serveru neexistují.

### Získejte jeden soubor

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

### Smažte soubor

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

Smazání se projeví okamžitě a nelze jej vrátit zpět. `503` znamená, že se smazání nedokončilo; odešlete `DELETE` znovu.

### Stahování

Nahrané soubory nelze stáhnout. `GET /api/v1/files/{file_id}/content` vrací `400 file_not_downloadable` a hlavička `Location` v odpovědi na nahrání ukazuje na metadata souboru, nikoli na jeho bajty. Vše, co nahráváte, si uchovejte ve vlastní kopii.

Chcete-li stáhnout vygenerovaná média, použijte podepsané URL v `outputs` úlohy.

## Reference API

Všechny endpointy používají `Authorization: Bearer YOUR_API_KEY`. Úspěšné odpovědi jsou prosté objekty JSON bez obálky.

| Metoda | Cesta | Vrací |
|---|---|---|
| `POST` | `/api/v1/files` | [Objekt souboru](#objekt-souboru) |
| `GET` | `/api/v1/files` | [Stránka souborů](#parametry-v-pisu) |
| `GET` | `/api/v1/files/{file_id}` | [Objekt souboru](#objekt-souboru) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` a `GET` jednoho souboru odmítnou jakýkoli parametr dotazu s `invalid_query`.

### Objekt souboru

| Pole | Typ | Popis |
|---|---|---|
| `id` | string | ID souboru s prefixem `felo_file_`. Použijte jej jako `file_id` |
| `type` | string | Vždy `file` |
| `source` | string | `upload` pro soubory, které jste nahráli, `generated` pro výstupy modelu |
| `filename` | string | Název odeslaný při nahrání |
| `mime_type` | string | Typ zjištěný z obsahu |
| `size_bytes` | integer | Velikost v bajtech |
| `created_at` | string | Časové razítko ISO 8601 v UTC |
| `downloadable` | boolean | `false` pro nahrané soubory |

### Požadavek na nahrání

| Část | Povinné | Popis |
|---|---|---|
| `file` | Ano | Soubor odeslaný jako souborová část `multipart/form-data` s názvem souboru |

Odpověď obsahuje hlavičku `Location` s URL metadat souboru.

### Parametry výpisu

| Parametr | Výchozí | Popis |
|---|---|---|
| `limit` | `100` | Velikost stránky, od 1 do 1000 |
| `cursor` | | Hodnota `cursor` z předchozí stránky |
| `after`, `after_id` | | Aliasy pro `cursor`. Odešlete pouze jeden z těchto tří |
| `order` | `asc` | Podporováno je pouze `asc` |

| Pole odpovědi | Typ | Popis |
|---|---|---|
| `data` | array | Objekty souborů, od nejstarších |
| `first_id` | string nebo null | ID prvního souboru na stránce |
| `last_id` | string nebo null | ID posledního souboru na stránce |
| `cursor` | string nebo null | Hodnota, kterou předáte jako `cursor` pro další stránku |
| `has_more` | boolean | Zda existuje další stránka |

## Chyby

Endpointy Files, Responses a generování obrázků a videa používají obálku chyb 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"
  }
}
```

U chyb z endpointů Files je `param` rovno `null`. Messages vrací tvar chyby Anthropic, který nemá `error.code`. ID požadavku je v hlavičce odpovědi `X-Request-Id`.

Chyby při nahrávání nebo správě souborů:

| HTTP | `error.code` | Význam |
|---|---|---|
| 400 | `invalid_content_type` | Tělo není `multipart/form-data` |
| 400 | `invalid_file` | Chybí část `file`, část navíc, prázdný soubor nebo nepodporovaný obsah |
| 400 | `invalid_filename` | Název souboru je příliš dlouhý nebo obsahuje nepovolený znak |
| 413 | `file_too_large` | Soubor přesahuje 100 MiB |
| 400 | `invalid_query` | Nepodporovaný parametr dotazu nebo `order` jiné než `asc` |
| 400 | `invalid_limit` | `limit` je mimo rozsah 1 až 1000 |
| 400 | `invalid_cursor` | Kurzor má chybný formát nebo byl odeslán více než jeden kurzor |
| 400 | `file_not_downloadable` | Byl vyžádán `/content` |
| 404 | `file_not_found` | Soubor neexistuje, byl smazán nebo patří jinému účtu |
| 503 | `file_storage_unavailable` | Úložiště souborů je dočasně nedostupné; opakujte později |
| 503 | `file_upload_expired` | Nahrání se nedokončilo včas; nahrajte soubor znovu |

Chyby při odkazování na soubor v požadavku na model:

| HTTP | `error.code` | Význam |
|---|---|---|
| 400 | `invalid_file_input` | ID s chybným formátem, `file_id` i `url` v jednom lokátoru nebo více než 100 odkazů |
| 400 | `unsupported_file_type` | Typ souboru neodpovídá pozici, například MP4 v bloku dokumentu |
| 400 | `file_model_unsupported` | Model nedeklaruje požadovanou vstupní modalitu |
| 400 | `file_input_too_large` | Odkazované soubory přesahují celkem 50,000,000 bajtů |
| 400 | `file_protocol_unsupported` | ID souboru bylo odesláno do Chat Completions |
| 404 | `file_not_found` | Soubor chybí, byl smazán, patří jinému účtu nebo jde o vygenerovaný soubor odeslaný do generování obrázků či videa |

U generování obrázků a videa může soubor selhat i po `202`. Úloha pak skončí jako `failed` s jedním z těchto kódů v `error.code`.

Chyby ověřování, zůstatku a limitů rychlosti jsou popsány v části [Chyby, limity a opakování](https://openapi.felo.ai/cs/docs/guides/errors-and-limits.md).

## Související

- [Protokoly a SDK](https://openapi.felo.ai/cs/docs/guides/protocols.md)
- [Generování obrázků](https://openapi.felo.ai/cs/docs/guides/image-generation.md)
- [Asynchronní úlohy](https://openapi.felo.ai/cs/docs/guides/async-tasks.md)
- [Reference Model API](https://openapi.felo.ai/cs/docs/model-api)
