Felo API PlatformFelo API Platform

Przewodniki

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

Szybki start

1. Przesłanie pliku

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:

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

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:

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:

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

EndpointTypy plikówWymagana modalność wejściowaPole
POST /api/v1/messagesPDF, obrazfile, imagemessages[].content[]
POST /api/v1/responsesPDF, obrazfile, imageinput[].content[]
POST /api/v1/images/generationsObrazimageinput_references[]
POST /api/v1/videos/generationsObrazimageframe_images[]
POST /api/v1/videos/generationsObraz, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNieobsługiwane

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

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

Responses

PlikBlok 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

{
  "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.

Generowanie wideo

Pierwsza i ostatnia klatka trafiają 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..."}
    }
  ]
}

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:

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

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
Co wysyłaszinput_modalities musi zawierać
PDFfile
Obrazimage
An MP4video
Plik audioaudio

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

LimitWartość
Rozmiar przesyłanego pliku100 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 modelu100
Długość nazwy pliku255 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.

TypFormatyGdzie można się odwołać
PDFPDFMessages, Responses
ObrazPNG, JPEG, GIF, WebPMessages, Responses, generowanie obrazów, generowanie wideo
WideoMP4Generowanie wideo
AudioMP3, WAV, FLAC, OGGGenerowanie wideo
OfficeDOCX, XLSX, PPTXTylko przechowywanie
TekstTekst UTF-8, zapisywany jako text/plainTylko 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

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
}

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

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

Usuwanie pliku

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

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żkaZwraca
POST/api/v1/filesObiekt pliku
GET/api/v1/filesStrona plików
GET/api/v1/files/{file_id}Obiekt pliku
DELETE/api/v1/files/{file_id}{"id": "...", "type": "file_deleted"}
GET/api/v1/files/{file_id}/content400 file_not_downloadable

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

Obiekt pliku

PoleTypOpis
idstringID pliku z prefiksem felo_file_. Używaj go jako file_id
typestringZawsze file
sourcestringupload dla plików przesłanych przez Ciebie, generated dla wyników modelu
filenamestringNazwa wysłana przy przesyłaniu
mime_typestringTyp wykryty na podstawie zawartości
size_bytesintegerRozmiar w bajtach
created_atstringZnacznik czasu ISO 8601 w UTC
downloadablebooleanfalse dla przesłanych plików

Żądanie przesłania

CzęśćWymaganeOpis
fileTakPlik wysłany jako część plikowa multipart/form-data z nazwą pliku

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

Parametry listy

ParametrDomyślnieOpis
limit100Rozmiar strony, od 1 do 1000
cursorWartość cursor z poprzedniej strony
after, after_idAliasy cursor. Wyślij tylko jeden z tych trzech
orderascObsługiwane jest tylko asc
Pole odpowiedziTypOpis
dataarrayObiekty plików, od najstarszych
first_idstring lub nullID pierwszego pliku na stronie
last_idstring lub nullID ostatniego pliku na stronie
cursorstring lub nullWartość do przekazania jako cursor dla następnej strony
has_morebooleanCzy istnieje kolejna strona

Błędy

Endpointy Files, Responses oraz generowanie obrazów i wideo używają koperty błędów 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"
  }
}

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:

HTTPerror.codeZnaczenie
400invalid_content_typeTreść nie jest multipart/form-data
400invalid_fileBrak części file, dodatkowa część, pusty plik lub nieobsługiwana zawartość
400invalid_filenameNazwa pliku jest za długa lub zawiera niedozwolony znak
413file_too_largePlik przekracza 100 MiB
400invalid_queryNieobsługiwany parametr zapytania lub order inne niż asc
400invalid_limitlimit jest poza zakresem od 1 do 1000
400invalid_cursorKursor jest nieprawidłowy lub wysłano więcej niż jeden kursor
400file_not_downloadableZażądano /content
404file_not_foundPlik nie istnieje, został usunięty lub należy do innego konta
503file_storage_unavailableMagazyn plików jest tymczasowo niedostępny; ponów później
503file_upload_expiredPrzesyłanie nie zakończyło się na czas; prześlij plik ponownie

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

HTTPerror.codeZnaczenie
400invalid_file_inputNieprawidłowy format ID, file_id i url w jednym lokatorze lub ponad 100 odwołań
400unsupported_file_typeTyp pliku nie pasuje do pozycji, na przykład MP4 w bloku dokumentu
400file_model_unsupportedModel nie deklaruje wymaganej modalności wejściowej
400file_input_too_largePliki, do których odwołuje się żądanie, przekraczają łącznie 50,000,000 bajtów
400file_protocol_unsupportedID pliku wysłano do Chat Completions
404file_not_foundPlik 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.

Powiązane

Potrzebujesz pomocy?