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
- Kunci API. Lihat Autentikasi.
- Base URL
https://openapi.felo.ai. - Model yang menerima jenis file yang akan Anda kirim. Lihat Periksa dukungan model.
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-datadengan tepat satu bagian, bernamafile. Bagian lain apa pun, termasukpurpose, ditolak denganinvalid_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 mengirimpurpose, 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
| Endpoint | Jenis file | Modalitas input yang diperlukan | Field |
|---|---|---|---|
POST /api/v1/messages | PDF, gambar | file, image | messages[].content[] |
POST /api/v1/responses | PDF, gambar | file, image | input[].content[] |
POST /api/v1/images/generations | Gambar | image | input_references[] |
POST /api/v1/videos/generations | Gambar | image | frame_images[] |
POST /api/v1/videos/generations | Gambar, MP4, audio | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Tidak 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
| File | Blok konten |
|---|---|
{"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, atauaudio_urlberisi tepat satu darifile_idatauurl, dan tidak ada field lain. - Satu array dapat mencampur entri yang menggunakan
file_iddengan entri yang menggunakanurl. - Generasi gambar dan video hanya menerima file yang Anda unggah. Untuk menggunakan kembali gambar yang dihasilkan, kirim
urloutput-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 mengirim | input_modalities harus menyertakan |
|---|---|
file | |
| Gambar | image |
| MP4 | video |
| File audio | audio |
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
| Batas | Nilai |
|---|---|
| Ukuran unggahan | 100 MiB (104,857,600 byte) per file; file kosong ditolak |
| Byte yang dirujuk per permintaan model | Total 50,000,000 byte |
| Referensi per permintaan model | 100 |
| Panjang nama file | 255 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.
| Jenis | Format | Dapat dirujuk di |
|---|---|---|
| Messages, Responses | ||
| Gambar | PNG, JPEG, GIF, WebP | Messages, Responses, generasi gambar, generasi video |
| Video | MP4 | Generasi video |
| Audio | MP3, WAV, FLAC, OGG | Generasi video |
| Office | DOCX, XLSX, PPTX | Hanya penyimpanan |
| Teks | Teks UTF-8, disimpan sebagai text/plain | Hanya 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.
| Metode | Path | Mengembalikan |
|---|---|---|
POST | /api/v1/files | Objek file |
GET | /api/v1/files | Satu 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}/content | 400 file_not_downloadable |
POST, DELETE, dan GET untuk satu file menolak parameter kueri apa pun dengan invalid_query.
Objek file
| Field | Tipe | Deskripsi |
|---|---|---|
id | string | ID file, berawalan felo_file_. Gunakan sebagai file_id |
type | string | Selalu file |
source | string | upload untuk file yang Anda unggah, generated untuk output model |
filename | string | Nama yang dikirim bersama unggahan |
mime_type | string | Jenis yang dideteksi dari konten |
size_bytes | integer | Ukuran dalam byte |
created_at | string | Stempel waktu UTC ISO 8601 |
downloadable | boolean | false untuk file yang diunggah |
Permintaan unggah
| Bagian | Wajib | Deskripsi |
|---|---|---|
file | Ya | File, dikirim sebagai bagian file multipart/form-data dengan nama file |
Respons menyertakan header Location berisi URL metadata file.
Parameter daftar
| Parameter | Default | Deskripsi |
|---|---|---|
limit | 100 | Ukuran halaman, dari 1 hingga 1000 |
cursor | Nilai cursor dari halaman sebelumnya | |
after, after_id | Alias dari cursor. Kirim hanya satu dari ketiganya | |
order | asc | Hanya asc yang didukung |
| Field respons | Tipe | Deskripsi |
|---|---|---|
data | array | Objek file, dari yang terlama |
first_id | string atau null | ID file pertama pada halaman |
last_id | string atau null | ID file terakhir pada halaman |
cursor | string atau null | Nilai yang dikirim sebagai cursor untuk halaman berikutnya |
has_more | boolean | Apakah 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:
| HTTP | error.code | Arti |
|---|---|---|
| 400 | invalid_content_type | Body bukan multipart/form-data |
| 400 | invalid_file | Tidak ada bagian file, ada bagian tambahan, file kosong, atau konten tidak didukung |
| 400 | invalid_filename | Nama file terlalu panjang atau berisi karakter yang ditolak |
| 413 | file_too_large | File melebihi 100 MiB |
| 400 | invalid_query | Parameter kueri yang tidak didukung, atau order selain asc |
| 400 | invalid_limit | limit di luar rentang 1 hingga 1000 |
| 400 | invalid_cursor | Cursor salah format, atau lebih dari satu cursor dikirim |
| 400 | file_not_downloadable | /content diminta |
| 404 | file_not_found | File tidak ada, telah dihapus, atau milik akun lain |
| 503 | file_storage_unavailable | Penyimpanan file sementara tidak tersedia; coba lagi nanti |
| 503 | file_upload_expired | Unggahan tidak selesai tepat waktu; unggah file lagi |
Error saat merujuk file dalam permintaan model:
| HTTP | error.code | Arti |
|---|---|---|
| 400 | invalid_file_input | ID salah format, file_id dan url sekaligus dalam satu locator, atau lebih dari 100 referensi |
| 400 | unsupported_file_type | Jenis file tidak sesuai dengan posisinya, misalnya MP4 di blok dokumen |
| 400 | file_model_unsupported | Model tidak mendeklarasikan modalitas input yang diperlukan |
| 400 | file_input_too_large | File yang dirujuk melebihi total 50,000,000 byte |
| 400 | file_protocol_unsupported | ID file dikirim ke Chat Completions |
| 404 | file_not_found | File 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?
- Ada pertanyaan soal API, penagihan, atau akun? Hubungi dukungan.
- Ngobrol dengan pengembang Felo di Discord.
- Lihat catatan perubahan kami.
- Butuh harga volume atau bantuan pengadaan? Hubungi penjualan.
- Sedang membangun dengan LLM? Baca llms.txt.