Felo API PlatformFelo API Platform

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

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

EndpointTypy souborůPožadovaná vstupní modalitaPole
POST /api/v1/messagesPDF, obrázekfile, imagemessages[].content[]
POST /api/v1/responsesPDF, obrázekfile, imageinput[].content[]
POST /api/v1/images/generationsObrázekimageinput_references[]
POST /api/v1/videos/generationsObrázekimageframe_images[]
POST /api/v1/videos/generationsObrázek, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNepodporová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

SouborBlok 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ů

{
  "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_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:

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áteinput_modalities musí obsahovat
PDFfile
Obrázekimage
An MP4video
Audio souboraudio

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

LimitHodnota
Velikost nahrávaného souboru100 MiB (104,857,600 bajtů) na soubor; prázdné soubory jsou odmítnuty
Velikost odkazovaných souborů na jeden požadavek na modelcelkem 50,000,000 bajtů
Počet odkazů na jeden požadavek na model100
Délka názvu souboru255 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.

TypFormátyKde na něj lze odkázat
PDFPDFMessages, Responses
ObrázekPNG, JPEG, GIF, WebPMessages, Responses, generování obrázků, generování videa
VideoMP4Generování videa
AudioMP3, WAV, FLAC, OGGGenerování videa
OfficeDOCX, XLSX, PPTXPouze uložení
TextText v UTF-8, uložený jako text/plainPouze 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.

MetodaCestaVrací
POST/api/v1/filesObjekt souboru
GET/api/v1/filesStrá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}/content400 file_not_downloadable

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

Objekt souboru

PoleTypPopis
idstringID souboru s prefixem felo_file_. Použijte jej jako file_id
typestringVždy file
sourcestringupload pro soubory, které jste nahráli, generated pro výstupy modelu
filenamestringNázev odeslaný při nahrání
mime_typestringTyp zjištěný z obsahu
size_bytesintegerVelikost v bajtech
created_atstringČasové razítko ISO 8601 v UTC
downloadablebooleanfalse pro nahrané soubory

Požadavek na nahrání

ČástPovinnéPopis
fileAnoSoubor odeslaný jako souborová část multipart/form-data s názvem souboru

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

Parametry výpisu

ParametrVýchozíPopis
limit100Velikost stránky, od 1 do 1000
cursorHodnota cursor z předchozí stránky
after, after_idAliasy pro cursor. Odešlete pouze jeden z těchto tří
orderascPodporováno je pouze asc
Pole odpovědiTypPopis
dataarrayObjekty souborů, od nejstarších
first_idstring nebo nullID prvního souboru na stránce
last_idstring nebo nullID posledního souboru na stránce
cursorstring nebo nullHodnota, kterou předáte jako cursor pro další stránku
has_morebooleanZda 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ů:

HTTPerror.codeVýznam
400invalid_content_typeTělo není multipart/form-data
400invalid_fileChybí část file, část navíc, prázdný soubor nebo nepodporovaný obsah
400invalid_filenameNázev souboru je příliš dlouhý nebo obsahuje nepovolený znak
413file_too_largeSoubor přesahuje 100 MiB
400invalid_queryNepodporovaný parametr dotazu nebo order jiné než asc
400invalid_limitlimit je mimo rozsah 1 až 1000
400invalid_cursorKurzor má chybný formát nebo byl odeslán více než jeden kurzor
400file_not_downloadableByl vyžádán /content
404file_not_foundSoubor neexistuje, byl smazán nebo patří jinému účtu
503file_storage_unavailableÚložiště souborů je dočasně nedostupné; opakujte později
503file_upload_expiredNahrání se nedokončilo včas; nahrajte soubor znovu

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

HTTPerror.codeVýznam
400invalid_file_inputID s chybným formátem, file_id i url v jednom lokátoru nebo více než 100 odkazů
400unsupported_file_typeTyp souboru neodpovídá pozici, například MP4 v bloku dokumentu
400file_model_unsupportedModel nedeklaruje požadovanou vstupní modalitu
400file_input_too_largeOdkazované soubory přesahují celkem 50,000,000 bajtů
400file_protocol_unsupportedID souboru bylo odesláno do Chat Completions
404file_not_foundSoubor 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?