Průvodci
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í.
- Základní URL
https://openapi.felo.ai. - Model přijímající typ souboru, který chcete odeslat. Viz Ověřte podporu modelu.
Rychlý start
1. Nahrajte soubor
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:
{
"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
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:
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:
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-datas právě jednou částí pojmenovanoufile. Jakákoli jiná část, včetněpurpose, je odmítnuta sinvalid_file. - Nastavení
Content-Typenechte 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
{
"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 |
|---|---|
{"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ů
{
"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ů.
Generování videa
První a poslední snímek patří do frame_images:
{
"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:
{
"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_urlneboaudio_urlprávě jedno z polífile_idnebourla žádné další pole. - V jednom poli lze kombinovat položky s
file_ida položky surl. - 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:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Co odesíláte | input_modalities musí obsahovat |
|---|---|
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 |
|---|---|---|
| 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
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
-H "Authorization: Bearer ${FELO_API_KEY}"{
"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
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Smažte soubor
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"{"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 |
GET | /api/v1/files | Stránka souborů |
GET | /api/v1/files/{file_id} | 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:
{
"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í.
Související
Potřebujete pomoc?
- S dotazy k API, fakturaci a účtu se obraťte na podporu.
- Popovídejte si s vývojáři Felo na Discord.
- Podívejte se na náš seznam změn.
- Potřebujete objemové ceny nebo pomoc s nákupem? Kontaktovat obchod.
- Vyvíjíte s LLM? Přečtěte si llms.txt.