Felo API PlatformFelo API Platform

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

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, file adlı tam olarak bir parça içeren multipart/form-data biçimindedir. purpose dahil başka herhangi bir parça invalid_file ile reddedilir.
  • Content-Type baş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 zaman purpose gö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

EndpointDosya türleriGerekli giriş modalitesiAlan
POST /api/v1/messagesPDF, görselfile, imagemessages[].content[]
POST /api/v1/responsesPDF, görselfile, imageinput[].content[]
POST /api/v1/images/generationsGörselimageinput_references[]
POST /api/v1/videos/generationsGörselimageframe_images[]
POST /api/v1/videos/generationsGörsel, MP4, sesimage, video, audioinput_references[]
POST /api/v1/chat/completionsDesteklenmiyor

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
PDF{"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_url veya audio_url nesnesi file_id veya url alanlarından tam olarak birini içerir ve başka alan içermez.
  • Tek bir dizide file_id kullanan girdilerle url kullanan 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ı url değ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önderilecekinput_modalities şunu içermelidir
PDFfile
Görselimage
MP4video
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ırDeğer
Yükleme boyutuDosya başına 100 MiB (104,857,600 bayt); boş dosyalar reddedilir
Model isteği başına başvurulan baytToplam 50,000,000 bayt
Model isteği başına referans100
Dosya adı uzunluğu255 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ürBiçimlerBaşvurulabileceği yerler
PDFPDFMessages, Responses
GörselPNG, JPEG, GIF, WebPMessages, Responses, görsel oluşturma, video oluşturma
VideoMP4Video oluşturma
SesMP3, WAV, FLAC, OGGVideo oluşturma
OfficeDOCX, XLSX, PPTXYalnızca depolama
Metintext/plain olarak depolanan UTF-8 metinYalnı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öntemYolDöndürdüğü
POST/api/v1/filesDosya nesnesi
GET/api/v1/filesDosya 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}/content400 file_not_downloadable

POST, DELETE ve tek dosyalık GET, her sorgu parametresini invalid_query ile reddeder.

Dosya nesnesi

AlanTürAçıklama
idstringfelo_file_ ön ekli dosya ID'si. file_id olarak kullanın
typestringHer zaman file
sourcestringYüklediğiniz dosyalar için upload, model çıktıları için generated
filenamestringYüklemeyle birlikte gönderilen ad
mime_typestringİçerikten algılanan tür
size_bytesintegerBayt cinsinden boyut
created_atstringISO 8601 UTC zaman damgası
downloadablebooleanYüklenen dosyalar için false

Yükleme isteği

ParçaGerekliAçıklama
fileEvetDosya 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

ParametreVarsayılanAçıklama
limit100Sayfa boyutu, 1 ile 1000 arasında
cursorÖnceki sayfadan gelen cursor değeri
after, after_idcursor için takma adlar. Üçünden yalnızca birini gönderin
orderascYalnızca asc desteklenir
Yanıt alanıTürAçıklama
dataarrayDosya nesneleri, en eskisi önce
first_idstring veya nullSayfadaki ilk dosyanın ID'si
last_idstring veya nullSayfadaki son dosyanın ID'si
cursorstring veya nullSonraki sayfa için cursor olarak geçirilecek değer
has_morebooleanBaş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:

HTTPerror.codeAnlamı
400invalid_content_typeGövde multipart/form-data değil
400invalid_filefile parçası yok, fazladan bir parça var, dosya boş veya içerik desteklenmiyor
400invalid_filenameDosya adı çok uzun veya reddedilen bir karakter içeriyor
413file_too_largeDosya 100 MiB sınırını aşıyor
400invalid_queryDesteklenmeyen bir sorgu parametresi veya asc dışında bir order değeri
400invalid_limitlimit 1 ile 1000 aralığının dışında
400invalid_cursorİmleç hatalı biçimlendirilmiş veya birden fazla imleç gönderildi
400file_not_downloadable/content istendi
404file_not_foundDosya mevcut değil, silinmiş veya başka bir hesaba ait
503file_storage_unavailableDosya depolama geçici olarak kullanılamıyor; daha sonra yeniden deneyin
503file_upload_expiredYükleme zamanında tamamlanmadı; dosyayı yeniden yükleyin

Bir model isteğinde dosyaya başvururken oluşan hatalar:

HTTPerror.codeAnlamı
400invalid_file_inputHatalı biçimlendirilmiş ID, tek bir konum belirleyicide hem file_id hem url veya 100'den fazla referans
400unsupported_file_typeDosyanın türü konumla eşleşmiyor, örneğin belge bloğunda bir MP4
400file_model_unsupportedModel gerekli giriş modalitesini bildirmiyor
400file_input_too_largeBaşvurulan dosyalar toplamda 50,000,000 baytı aşıyor
400file_protocol_unsupportedChat Completions'a bir dosya ID'si gönderildi
404file_not_foundDosya 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?