Felo API PlatformFelo API Platform

Panduan

Unggah file

Unggah file sekali, lalu rujuk dengan ID dalam permintaan Messages, Responses, pembuatan gambar, dan pembuatan video.

Unggah file satu kali, lalu rujuk file itu dengan ID-nya dalam permintaan model. Cara ini menggantikan pengiriman ulang byte yang sama sebagai base64 atau hosting file di URL publik.

ID file dapat digunakan dengan Messages, Responses, generasi gambar, dan generasi video. ID file tidak dapat digunakan dengan Chat Completions.

Sebelum Anda memulai

Mulai cepat

1. Unggah file

curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"

Unggahan yang berhasil mengembalikan HTTP 200 beserta metadata file:

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

Simpan id. Perlakukan sebagai string opak: jangan menyusunnya sendiri atau mengurainya.

2. Rujuk file dalam permintaan

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

Dua langkah yang sama dalam Python:

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

Dan dalam Node.js 20 atau yang lebih baru:

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");

Aturan unggah

  • Body berupa multipart/form-data dengan tepat satu bagian, bernama file. Bagian lain apa pun, termasuk purpose, ditolak dengan invalid_file.
  • Biarkan klien HTTP Anda yang menetapkan Content-Type. Menetapkannya secara manual akan menghilangkan multipart boundary.
  • Jangan menambahkan parameter kueri ke URL unggah.
  • Unggah melalui HTTP, bukan melalui helper Files milik SDK. files.create() pada OpenAI SDK selalu mengirim purpose, sehingga tidak dapat memanggil endpoint ini.
  • Unggahan yang kehabisan waktu atau terputus mungkin tetap tersimpan. Tampilkan daftar file Anda sebelum mengunggah lagi.

Di mana ID file dapat digunakan

EndpointJenis fileModalitas input yang diperlukanField
POST /api/v1/messagesPDF, gambarfile, imagemessages[].content[]
POST /api/v1/responsesPDF, gambarfile, imageinput[].content[]
POST /api/v1/images/generationsGambarimageinput_references[]
POST /api/v1/videos/generationsGambarimageframe_images[]
POST /api/v1/videos/generationsGambar, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsTidak didukung

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

Untuk gambar, gunakan {"type": "image", "source": {"type": "file", "file_id": "..."}}.

Responses

FileBlok konten
PDF{"type": "input_file", "file_id": "..."}
Gambar{"type": "input_image", "file_id": "...", "detail": "auto"}

Blok yang memuat file_id tidak boleh sekaligus memuat URL atau data base64.

Generasi gambar

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

Bagian lain dari permintaan, respons 202, dan polling dijelaskan di Generasi Gambar.

Generasi video

Frame pertama dan terakhir ditempatkan di 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..."}
    }
  ]
}

Tambahkan entri kedua dengan "frame_type": "last_frame" untuk frame akhir. Frame terakhir memerlukan frame pertama.

Materi referensi ditempatkan di input_references. Setiap entri menggunakan locator yang sesuai dengan jenis medianya:

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

Kombinasi mana yang diterima sebuah model bergantung pada model dan kanalnya. frame_images dan input_references tidak dapat digunakan dalam permintaan yang sama.

Aturan locator

  • Dalam permintaan gambar dan video, setiap objek image_url, video_url, atau audio_url berisi tepat satu dari file_id atau url, dan tidak ada field lain.
  • Satu array dapat mencampur entri yang menggunakan file_id dengan entri yang menggunakan url.
  • Generasi gambar dan video hanya menerima file yang Anda unggah. Untuk menggunakan kembali gambar yang dihasilkan, kirim url output-nya.
  • Permintaan yang merujuk file tidak dipindahkan ke kanal lain saat gagal. Jangan mencobanya ulang di kanal lain tanpa memeriksa error-nya.
  • Simpan file hingga setiap tugas yang merujuknya mencapai status terminal. Menghapusnya lebih awal dapat menggagalkan tugas.

Periksa dukungan model

File yang tersimpan tidak otomatis dapat digunakan dengan setiap model. Model harus mendeklarasikan modalitas input yang sesuai di katalog publik:

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
Untuk mengiriminput_modalities harus menyertakan
PDFfile
Gambarimage
MP4video
File audioaudio

Daftar yang kosong atau tidak ada berarti ID file tidak diaktifkan untuk model tersebut. Permintaan kemudian gagal dengan file_model_unsupported. Jangan menyimpulkan dukungan dari nama model.

Batas

BatasNilai
Ukuran unggahan100 MiB (104,857,600 byte) per file; file kosong ditolak
Byte yang dirujuk per permintaan modelTotal 50,000,000 byte
Referensi per permintaan model100
Panjang nama file255 karakter

Merujuk file yang sama dua kali dihitung dua kali terhadap kedua batas permintaan. File berukuran antara 50 MB dan 100 MiB dapat diunggah tetapi tidak dapat dirujuk dalam permintaan model. Model atau kanal dapat menerapkan batas yang lebih rendah.

Jenis file

Jenis dideteksi dari konten file, bukan dari ekstensinya atau Content-Type bagian tersebut.

JenisFormatDapat dirujuk di
PDFPDFMessages, Responses
GambarPNG, JPEG, GIF, WebPMessages, Responses, generasi gambar, generasi video
VideoMP4Generasi video
AudioMP3, WAV, FLAC, OGGGenerasi video
OfficeDOCX, XLSX, PPTXHanya penyimpanan
TeksTeks UTF-8, disimpan sebagai text/plainHanya penyimpanan

Konten lain apa pun ditolak dengan invalid_file.

Nama file

Nama file tidak boleh berisi <, >, :, ", |, ?, *, \, atau karakter kontrol. / diperbolehkan sebagai pemisah, tetapi segmen kosong, ., dan .. tidak.

Mengelola file

File adalah milik akun Anda. Setiap kunci API pada akun melihat file yang sama; akun lain tidak dapat menggunakan ID file Anda.

Menampilkan daftar file

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
}

Hasil diurutkan dari yang terlama. Jika has_more bernilai true, kirim cursor yang dikembalikan untuk mendapatkan halaman berikutnya. Tidak ada pencarian atau filter jenis di sisi server.

Mengambil satu file

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

Menghapus file

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

Penghapusan langsung berlaku dan tidak dapat dibatalkan. 503 berarti penghapusan tidak selesai; kirim DELETE lagi.

Unduhan

File yang diunggah tidak dapat diunduh. GET /api/v1/files/{file_id}/content mengembalikan 400 file_not_downloadable, dan header Location pada respons unggah menunjuk ke metadata file, bukan byte-nya. Simpan salinan Anda sendiri untuk apa pun yang Anda unggah.

Untuk mengunduh media yang dihasilkan, gunakan URL bertanda tangan di outputs tugas.

Referensi API

Semua endpoint menggunakan Authorization: Bearer YOUR_API_KEY. Respons yang berhasil berupa objek JSON biasa tanpa envelope.

MetodePathMengembalikan
POST/api/v1/filesObjek file
GET/api/v1/filesSatu halaman file
GET/api/v1/files/{file_id}Objek file
DELETE/api/v1/files/{file_id}{"id": "...", "type": "file_deleted"}
GET/api/v1/files/{file_id}/content400 file_not_downloadable

POST, DELETE, dan GET untuk satu file menolak parameter kueri apa pun dengan invalid_query.

Objek file

FieldTipeDeskripsi
idstringID file, berawalan felo_file_. Gunakan sebagai file_id
typestringSelalu file
sourcestringupload untuk file yang Anda unggah, generated untuk output model
filenamestringNama yang dikirim bersama unggahan
mime_typestringJenis yang dideteksi dari konten
size_bytesintegerUkuran dalam byte
created_atstringStempel waktu UTC ISO 8601
downloadablebooleanfalse untuk file yang diunggah

Permintaan unggah

BagianWajibDeskripsi
fileYaFile, dikirim sebagai bagian file multipart/form-data dengan nama file

Respons menyertakan header Location berisi URL metadata file.

Parameter daftar

ParameterDefaultDeskripsi
limit100Ukuran halaman, dari 1 hingga 1000
cursorNilai cursor dari halaman sebelumnya
after, after_idAlias dari cursor. Kirim hanya satu dari ketiganya
orderascHanya asc yang didukung
Field responsTipeDeskripsi
dataarrayObjek file, dari yang terlama
first_idstring atau nullID file pertama pada halaman
last_idstring atau nullID file terakhir pada halaman
cursorstring atau nullNilai yang dikirim sebagai cursor untuk halaman berikutnya
has_morebooleanApakah ada halaman lain

Error

Endpoint Files, Responses, serta generasi gambar dan video menggunakan envelope error 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"
  }
}

param bernilai null untuk error dari endpoint Files. Messages mengembalikan bentuk error Anthropic, yang tidak memiliki error.code. ID permintaan berada di header respons X-Request-Id.

Error saat mengunggah atau mengelola file:

HTTPerror.codeArti
400invalid_content_typeBody bukan multipart/form-data
400invalid_fileTidak ada bagian file, ada bagian tambahan, file kosong, atau konten tidak didukung
400invalid_filenameNama file terlalu panjang atau berisi karakter yang ditolak
413file_too_largeFile melebihi 100 MiB
400invalid_queryParameter kueri yang tidak didukung, atau order selain asc
400invalid_limitlimit di luar rentang 1 hingga 1000
400invalid_cursorCursor salah format, atau lebih dari satu cursor dikirim
400file_not_downloadable/content diminta
404file_not_foundFile tidak ada, telah dihapus, atau milik akun lain
503file_storage_unavailablePenyimpanan file sementara tidak tersedia; coba lagi nanti
503file_upload_expiredUnggahan tidak selesai tepat waktu; unggah file lagi

Error saat merujuk file dalam permintaan model:

HTTPerror.codeArti
400invalid_file_inputID salah format, file_id dan url sekaligus dalam satu locator, atau lebih dari 100 referensi
400unsupported_file_typeJenis file tidak sesuai dengan posisinya, misalnya MP4 di blok dokumen
400file_model_unsupportedModel tidak mendeklarasikan modalitas input yang diperlukan
400file_input_too_largeFile yang dirujuk melebihi total 50,000,000 byte
400file_protocol_unsupportedID file dikirim ke Chat Completions
404file_not_foundFile tidak ada, telah dihapus, dimiliki akun lain, atau merupakan file hasil generasi yang dikirim ke generasi gambar atau video

Untuk generasi gambar dan video, file juga dapat gagal setelah 202. Tugas kemudian berakhir sebagai failed dengan salah satu kode ini di error.code.

Error autentikasi, saldo, dan batas laju dijelaskan di Error, Batas, dan Percobaan Ulang.

Terkait

Butuh bantuan?