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
- Klucz API. Zobacz Uwierzytelnianie.
- Bazowy adres URL
https://openapi.felo.ai. - Model, który akceptuje typ pliku, jaki zamierzasz wysłać. Zobacz Sprawdzanie obsługi przez model.
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-dataz dokładnie jedną częścią o nazwiefile. Każda inna część, w tympurpose, jest odrzucana z kodeminvalid_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łapurpose, 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
{
"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 |
|---|---|
{"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_urllubaudio_urlzawiera dokładnie jedno z pólfile_idalbourli żadnego innego pola. - Jedna tablica może łączyć wpisy używające
file_idz wpisami używającymiurl. - 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łasz | input_modalities musi zawierać |
|---|---|
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ć |
|---|---|---|
| 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
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żka | Zwraca |
|---|---|---|
POST | /api/v1/files | Obiekt pliku |
GET | /api/v1/files | Strona 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}/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:
{
"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.
Powiązane
Potrzebujesz pomocy?
- W sprawach API, płatności i konta napisz do wsparcia.
- Porozmawiaj z deweloperami Felo na Discord.
- Sprawdź nasz dziennik zmian.
- Potrzebujesz cen hurtowych lub pomocy w zakupach? Skontaktuj się z działem sprzedaży.
- Budujesz z LLM? Przeczytaj llms.txt.