Kılavuzlar
Dosya yükleme
Dosyayı bir kez yükleyin, ardından Messages, Responses, görsel üretimi ve video üretimi isteklerinde ID ile başvurun.
Bir dosyayı bir kez yükleyin, ardından model isteklerinde ona ID'siyle başvurun. Bu, aynı baytları base64 olarak yeniden göndermenin veya dosyayı herkese açık bir URL'de barındırmanın yerini alır.
Dosya ID'si Messages, Responses, görsel oluşturma ve video oluşturma ile çalışır. Chat Completions ile çalışmaz.
Başlamadan önce
- Bir API anahtarı. Bkz. Kimlik Doğrulama.
https://openapi.felo.aitemel URL'si.- Göndermeyi planladığınız dosya türünü kabul eden bir model. Bkz. Model desteğini kontrol etme.
Hızlı başlangıç
1. Dosyayı yükleme
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"Başarılı bir yükleme, dosyanın meta verileriyle birlikte HTTP 200 döndürür:
{
"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
}id değerini saklayın. Onu opak bir dize olarak ele alın: kendiniz oluşturmayın veya ayrıştırmayın.
2. Dosyaya bir istekte başvurma
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."}
]
}
]
}'Aynı iki adım Python ile:
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())Node.js 20 veya üzeri ile:
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");Yükleme kuralları
- Gövde,
fileadlı tam olarak bir parça içerenmultipart/form-databiçimindedir.purposedahil başka herhangi bir parçainvalid_fileile reddedilir. Content-Typebaşlığını HTTP istemcinizin ayarlamasına izin verin. Elle ayarlamak multipart boundary değerinin kaybolmasına yol açar.- Yükleme URL'sine sorgu parametreleri eklemeyin.
- Bir SDK'nın Files yardımcısı yerine HTTP üzerinden yükleyin. OpenAI SDK'sının
files.create()yöntemi her zamanpurposegönderir, bu nedenle bu endpoint'i çağıramaz. - Zaman aşımına uğrayan veya bağlantısı kopan bir yükleme yine de depolanmış olabilir. Yeniden yüklemeden önce dosyalarınızı listeleyin.
Dosya ID'si nerede kullanılabilir
| Endpoint | Dosya türleri | Gerekli giriş modalitesi | Alan |
|---|---|---|---|
POST /api/v1/messages | PDF, görsel | file, image | messages[].content[] |
POST /api/v1/responses | PDF, görsel | file, image | input[].content[] |
POST /api/v1/images/generations | Görsel | image | input_references[] |
POST /api/v1/videos/generations | Görsel | image | frame_images[] |
POST /api/v1/videos/generations | Görsel, MP4, ses | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Desteklenmiyor |
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."}
]
}
]
}Görsel için {"type": "image", "source": {"type": "file", "file_id": "..."}} kullanın.
Responses
| Dosya | İçerik bloğu |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Görsel | {"type": "input_image", "file_id": "...", "detail": "auto"} |
file_id taşıyan bir blok ayrıca URL veya base64 verisi taşımamalıdır.
Görsel oluşturma
{
"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..."}}
]
}İsteğin geri kalanı, 202 yanıtı ve yoklama Görsel Oluşturma sayfasında açıklanmıştır.
Video oluşturma
İlk ve son kareler frame_images içinde yer alır:
{
"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..."}
}
]
}Bitiş karesi için "frame_type": "last_frame" içeren ikinci bir girdi ekleyin. Son kare, bir ilk kare gerektirir.
Referans materyali input_references içinde yer alır. Her girdi, kendi medya türüyle eşleşen konum belirleyiciyi kullanır:
{
"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"}}
]
}Bir modelin hangi kombinasyonları kabul ettiği modele ve kanala bağlıdır. frame_images ve input_references aynı istekte kullanılamaz.
Konum belirleyici kuralları
- Görsel ve video isteklerinde her
image_url,video_urlveyaaudio_urlnesnesifile_idveyaurlalanlarından tam olarak birini içerir ve başka alan içermez. - Tek bir dizide
file_idkullanan girdilerleurlkullanan girdiler bir arada bulunabilir. - Görsel ve video oluşturma yalnızca sizin yüklediğiniz dosyaları kabul eder. Oluşturulmuş bir görseli yeniden kullanmak için çıktı
urldeğerini geçirin. - Bir dosyaya başvuran istek, hata durumunda başka bir kanala taşınmaz. Hatayı kontrol etmeden farklı bir kanalda yeniden denemeyin.
- Bir dosyayı, ona başvuran tüm görevler nihai bir duruma ulaşana kadar saklayın. Daha önce silmek görevin başarısız olmasına yol açabilir.
Model desteğini kontrol etme
Depolanan bir dosya her modelle otomatik olarak kullanılamaz. Model, eşleşen giriş modalitesini herkese açık katalogda bildirmelidir:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Gönderilecek | input_modalities şunu içermelidir |
|---|---|
file | |
| Görsel | image |
| MP4 | video |
| Ses dosyası | audio |
Boş veya eksik bir liste, o model için dosya ID'lerinin etkin olmadığı anlamına gelir. Bu durumda istek file_model_unsupported ile başarısız olur. Destek olup olmadığını model adından çıkarsamayın.
Sınırlar
| Sınır | Değer |
|---|---|
| Yükleme boyutu | Dosya başına 100 MiB (104,857,600 bayt); boş dosyalar reddedilir |
| Model isteği başına başvurulan bayt | Toplam 50,000,000 bayt |
| Model isteği başına referans | 100 |
| Dosya adı uzunluğu | 255 karakter |
Aynı dosyaya iki kez başvurmak, her iki istek sınırı için de iki kez sayılır. 50 MB ile 100 MiB arasındaki bir dosya yüklenebilir ancak bir model isteğinde ona başvurulamaz. Bir model veya kanal daha düşük bir sınır uygulayabilir.
Dosya türleri
Tür, dosyanın uzantısından veya parçanın Content-Type değerinden değil, dosyanın içeriğinden algılanır.
| Tür | Biçimler | Başvurulabileceği yerler |
|---|---|---|
| Messages, Responses | ||
| Görsel | PNG, JPEG, GIF, WebP | Messages, Responses, görsel oluşturma, video oluşturma |
| Video | MP4 | Video oluşturma |
| Ses | MP3, WAV, FLAC, OGG | Video oluşturma |
| Office | DOCX, XLSX, PPTX | Yalnızca depolama |
| Metin | text/plain olarak depolanan UTF-8 metin | Yalnızca depolama |
Diğer tüm içerikler invalid_file ile reddedilir.
Dosya adları
Dosya adı <, >, :, ", |, ?, *, \ veya kontrol karakterleri içeremez. / ayırıcı olarak kullanılabilir, ancak boş bölümlere, . ve .. kullanımına izin verilmez.
Dosyaları yönetme
Dosyalar hesabınıza aittir. Hesaptaki her API anahtarı aynı dosyaları görür; diğer hesaplar dosya ID'lerinizi kullanamaz.
Dosyaları listeleme
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
}Sonuçlar en eskiden en yeniye doğru sıralanır. has_more değeri true olduğunda, sonraki sayfayı almak için dönen cursor değerini geçirin. Sunucu tarafında arama veya tür filtresi yoktur.
Tek bir dosyayı alma
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Dosya silme
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"}Silme hemen geçerli olur ve geri alınamaz. 503, silmenin tamamlanmadığı anlamına gelir; DELETE isteğini yeniden gönderin.
İndirmeler
Yüklenen dosyalar indirilemez. GET /api/v1/files/{file_id}/content, 400 file_not_downloadable döndürür ve yükleme yanıtının Location başlığı dosyanın baytlarını değil, meta verilerini gösterir. Yüklediğiniz her şeyin bir kopyasını kendinizde saklayın.
Oluşturulan medyayı indirmek için görevin outputs alanındaki imzalı URL'leri kullanın.
API referansı
Tüm endpoint'ler Authorization: Bearer YOUR_API_KEY kullanır. Başarılı yanıtlar, zarf içermeyen düz JSON nesneleridir.
| Yöntem | Yol | Döndürdüğü |
|---|---|---|
POST | /api/v1/files | Dosya nesnesi |
GET | /api/v1/files | Dosya sayfası |
GET | /api/v1/files/{file_id} | Dosya nesnesi |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST, DELETE ve tek dosyalık GET, her sorgu parametresini invalid_query ile reddeder.
Dosya nesnesi
| Alan | Tür | Açıklama |
|---|---|---|
id | string | felo_file_ ön ekli dosya ID'si. file_id olarak kullanın |
type | string | Her zaman file |
source | string | Yüklediğiniz dosyalar için upload, model çıktıları için generated |
filename | string | Yüklemeyle birlikte gönderilen ad |
mime_type | string | İçerikten algılanan tür |
size_bytes | integer | Bayt cinsinden boyut |
created_at | string | ISO 8601 UTC zaman damgası |
downloadable | boolean | Yüklenen dosyalar için false |
Yükleme isteği
| Parça | Gerekli | Açıklama |
|---|---|---|
file | Evet | Dosya adıyla birlikte multipart/form-data dosya parçası olarak gönderilen dosya |
Yanıt, dosyanın meta verilerinin URL'sini taşıyan bir Location başlığı içerir.
Liste parametreleri
| Parametre | Varsayılan | Açıklama |
|---|---|---|
limit | 100 | Sayfa boyutu, 1 ile 1000 arasında |
cursor | Önceki sayfadan gelen cursor değeri | |
after, after_id | cursor için takma adlar. Üçünden yalnızca birini gönderin | |
order | asc | Yalnızca asc desteklenir |
| Yanıt alanı | Tür | Açıklama |
|---|---|---|
data | array | Dosya nesneleri, en eskisi önce |
first_id | string veya null | Sayfadaki ilk dosyanın ID'si |
last_id | string veya null | Sayfadaki son dosyanın ID'si |
cursor | string veya null | Sonraki sayfa için cursor olarak geçirilecek değer |
has_more | boolean | Başka bir sayfa olup olmadığı |
Hatalar
Files endpoint'leri, Responses ile görsel ve video oluşturma OpenAI hata zarfını kullanır:
{
"error": {
"message": "This model does not accept this attachment type",
"type": "invalid_request_error",
"param": "frame_images.0.image_url",
"code": "file_model_unsupported"
}
}Files endpoint'lerinden gelen hatalarda param değeri null olur. Messages, error.code içermeyen Anthropic hata biçimini döndürür. İstek ID'si X-Request-Id yanıt başlığındadır.
Dosya yüklerken veya yönetirken oluşan hatalar:
| HTTP | error.code | Anlamı |
|---|---|---|
| 400 | invalid_content_type | Gövde multipart/form-data değil |
| 400 | invalid_file | file parçası yok, fazladan bir parça var, dosya boş veya içerik desteklenmiyor |
| 400 | invalid_filename | Dosya adı çok uzun veya reddedilen bir karakter içeriyor |
| 413 | file_too_large | Dosya 100 MiB sınırını aşıyor |
| 400 | invalid_query | Desteklenmeyen bir sorgu parametresi veya asc dışında bir order değeri |
| 400 | invalid_limit | limit 1 ile 1000 aralığının dışında |
| 400 | invalid_cursor | İmleç hatalı biçimlendirilmiş veya birden fazla imleç gönderildi |
| 400 | file_not_downloadable | /content istendi |
| 404 | file_not_found | Dosya mevcut değil, silinmiş veya başka bir hesaba ait |
| 503 | file_storage_unavailable | Dosya depolama geçici olarak kullanılamıyor; daha sonra yeniden deneyin |
| 503 | file_upload_expired | Yükleme zamanında tamamlanmadı; dosyayı yeniden yükleyin |
Bir model isteğinde dosyaya başvururken oluşan hatalar:
| HTTP | error.code | Anlamı |
|---|---|---|
| 400 | invalid_file_input | Hatalı biçimlendirilmiş ID, tek bir konum belirleyicide hem file_id hem url veya 100'den fazla referans |
| 400 | unsupported_file_type | Dosyanın türü konumla eşleşmiyor, örneğin belge bloğunda bir MP4 |
| 400 | file_model_unsupported | Model gerekli giriş modalitesini bildirmiyor |
| 400 | file_input_too_large | Başvurulan dosyalar toplamda 50,000,000 baytı aşıyor |
| 400 | file_protocol_unsupported | Chat Completions'a bir dosya ID'si gönderildi |
| 404 | file_not_found | Dosya mevcut değil, silinmiş, başka bir hesaba ait veya görsel ya da video oluşturmaya gönderilen oluşturulmuş bir dosya |
Görsel ve video oluşturmada bir dosya 202 yanıtından sonra da başarısız olabilir. Bu durumda görev, error.code içinde bu kodlardan biriyle failed olarak sona erer.
Kimlik doğrulama, bakiye ve hız sınırı hataları Hatalar, Sınırlar ve Yeniden Denemeler bölümünde açıklanmıştır.
İlgili
Yardım mı gerekiyor?
- API, faturalama ve hesap sorularınız için destek ekibi ile iletişime geçin.
- Felo geliştiricileriyle Discord üzerinden sohbet edin.
- değişiklik günlüğü sayfamıza göz atın.
- Hacim fiyatlandırması veya satın alma desteği mi gerekiyor? Satış ekibiyle iletişime geçin.
- LLM ile mi geliştiriyorsunuz? llms.txt belgesini okuyun.