Panduan
Muat naik fail
Muat naik fail sekali, kemudian rujuk dengan ID dalam permintaan Messages, Responses, penjanaan imej dan penjanaan video.
Muat naik fail sekali, kemudian rujuk fail itu melalui ID dalam permintaan model. Ini menggantikan penghantaran semula bait yang sama sebagai base64 atau pengehosan fail di URL awam.
ID fail berfungsi dengan Messages, Responses, penjanaan imej, dan penjanaan video. Ia tidak berfungsi dengan Chat Completions.
Sebelum anda bermula
- Kunci API. Lihat Pengesahan.
- URL asas
https://openapi.felo.ai. - Model yang menerima jenis fail yang anda ingin hantar. Lihat Semak sokongan model.
Mula pantas
1. Muat naik fail
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"Muat naik yang berjaya mengembalikan HTTP 200 dengan metadata fail:
{
"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. Anggap ia sebagai rentetan legap: jangan bina atau huraikannya sendiri.
2. Rujuk fail 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 lebih baharu:
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");Peraturan muat naik
- Badan ialah
multipart/form-datadengan tepat satu bahagian, bernamafile. Sebarang bahagian lain, termasukpurpose, ditolak denganinvalid_file. - Biarkan klien HTTP anda menetapkan
Content-Type. Menetapkannya secara manual akan menggugurkan multipart boundary. - Jangan tambah parameter pertanyaan pada URL muat naik.
- Muat naik melalui HTTP dan bukannya melalui pembantu Files SDK.
files.create()dalam SDK OpenAI sentiasa menghantarpurpose, jadi ia tidak boleh memanggil endpoint ini. - Muat naik yang tamat masa atau terputus mungkin masih telah disimpan. Senaraikan fail anda sebelum memuat naik semula.
Tempat ID fail boleh digunakan
| Endpoint | Jenis fail | Modaliti input yang diperlukan | Medan |
|---|---|---|---|
POST /api/v1/messages | PDF, imej | file, image | messages[].content[] |
POST /api/v1/responses | PDF, imej | file, image | input[].content[] |
POST /api/v1/images/generations | Imej | image | input_references[] |
POST /api/v1/videos/generations | Imej | image | frame_images[] |
POST /api/v1/videos/generations | Imej, MP4, audio | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Tidak disokong |
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 imej, gunakan {"type": "image", "source": {"type": "file", "file_id": "..."}}.
Responses
| Fail | Blok kandungan |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Imej | {"type": "input_image", "file_id": "...", "detail": "auto"} |
Blok yang membawa file_id tidak boleh turut membawa URL atau data base64.
Penjanaan imej
{
"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..."}}
]
}Bahagian permintaan yang selebihnya, respons 202, dan tinjauan diterangkan dalam Penjanaan Imej.
Penjanaan video
Bingkai pertama dan terakhir diletakkan dalam 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..."}
}
]
}Tambah entri kedua dengan "frame_type": "last_frame" untuk bingkai akhir. Bingkai terakhir memerlukan bingkai pertama.
Bahan rujukan diletakkan dalam input_references. Setiap entri menggunakan locator yang sepadan 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"}}
]
}Gabungan yang diterima oleh sesuatu model bergantung pada model dan saluran. frame_images dan input_references tidak boleh digunakan dalam permintaan yang sama.
Peraturan locator
- Dalam permintaan imej dan video, setiap objek
image_url,video_url, atauaudio_urlmengandungi tepat satu daripadafile_idatauurl, dan tiada medan lain. - Satu tatasusunan boleh mencampurkan entri yang menggunakan
file_iddengan entri yang menggunakanurl. - Penjanaan imej dan video hanya menerima fail yang anda muat naik. Untuk menggunakan semula imej yang dijana, hantar
urloutputnya. - Permintaan yang merujuk fail tidak dipindahkan ke saluran lain apabila gagal. Jangan cuba semula pada saluran lain tanpa menyemak ralatnya.
- Simpan fail sehingga setiap tugasan yang merujuknya mencapai keadaan terminal. Memadamnya lebih awal boleh menyebabkan tugasan gagal.
Semak sokongan model
Fail yang disimpan tidak semestinya boleh digunakan dengan setiap model secara automatik. Model mesti mengisytiharkan modaliti input yang sepadan dalam katalog awam:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Untuk menghantar | input_modalities mesti mengandungi |
|---|---|
file | |
| Imej | image |
| MP4 | video |
| Fail audio | audio |
Senarai yang kosong atau tiada bermaksud ID fail tidak didayakan untuk model itu. Permintaan kemudiannya gagal dengan file_model_unsupported. Jangan buat andaian tentang sokongan berdasarkan nama model.
Had
| Had | Nilai |
|---|---|
| Saiz muat naik | 100 MiB (104,857,600 bait) setiap fail; fail kosong ditolak |
| Bait yang dirujuk setiap permintaan model | 50,000,000 bait secara keseluruhan |
| Rujukan setiap permintaan model | 100 |
| Panjang nama fail | 255 aksara |
Merujuk fail yang sama dua kali dikira dua kali terhadap kedua-dua had permintaan. Fail antara 50 MB dan 100 MiB boleh dimuat naik tetapi tidak boleh dirujuk dalam permintaan model. Model atau saluran boleh mengenakan had yang lebih rendah.
Jenis fail
Jenis dikesan daripada kandungan fail, bukan daripada sambungannya atau Content-Type bahagian itu.
| Jenis | Format | Boleh dirujuk dalam |
|---|---|---|
| Messages, Responses | ||
| Imej | PNG, JPEG, GIF, WebP | Messages, Responses, penjanaan imej, penjanaan video |
| Video | MP4 | Penjanaan video |
| Audio | MP3, WAV, FLAC, OGG | Penjanaan video |
| Office | DOCX, XLSX, PPTX | Storan sahaja |
| Teks | Teks UTF-8, disimpan sebagai text/plain | Storan sahaja |
Sebarang kandungan lain ditolak dengan invalid_file.
Nama fail
Nama fail tidak boleh mengandungi <, >, :, ", |, ?, *, \, atau aksara kawalan. / dibenarkan sebagai pemisah, tetapi segmen kosong, ., dan .. tidak dibenarkan.
Urus fail
Fail adalah milik akaun anda. Setiap kunci API dalam akaun melihat fail yang sama; akaun lain tidak boleh menggunakan ID fail anda.
Senaraikan fail
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 disusun bermula daripada yang paling lama. Apabila has_more ialah true, hantar cursor yang dikembalikan untuk mendapatkan halaman seterusnya. Tiada carian atau penapis jenis di sisi pelayan.
Dapatkan satu fail
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Padam fail
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"}Pemadaman berkuat kuasa serta-merta dan tidak boleh dibuat asal. 503 bermaksud pemadaman tidak selesai; hantar DELETE sekali lagi.
Muat turun
Fail yang dimuat naik tidak boleh dimuat turun. GET /api/v1/files/{file_id}/content mengembalikan 400 file_not_downloadable, dan pengepala Location pada respons muat naik menunjuk ke metadata fail, bukan baitnya. Simpan salinan anda sendiri bagi apa-apa yang anda muat naik.
Untuk memuat turun media yang dijana, gunakan URL bertandatangan dalam outputs tugasan.
Rujukan API
Semua endpoint menggunakan Authorization: Bearer YOUR_API_KEY. Respons yang berjaya ialah objek JSON biasa tanpa sampul.
| Kaedah | Laluan | Mengembalikan |
|---|---|---|
POST | /api/v1/files | Objek fail |
GET | /api/v1/files | Satu halaman fail |
GET | /api/v1/files/{file_id} | Objek fail |
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 fail menolak sebarang parameter pertanyaan dengan invalid_query.
Objek fail
| Medan | Jenis | Penerangan |
|---|---|---|
id | string | ID fail, berawalan felo_file_. Gunakannya sebagai file_id |
type | string | Sentiasa file |
source | string | upload untuk fail yang anda muat naik, generated untuk output model |
filename | string | Nama yang dihantar bersama muat naik |
mime_type | string | Jenis yang dikesan daripada kandungan |
size_bytes | integer | Saiz dalam bait |
created_at | string | Cap masa UTC ISO 8601 |
downloadable | boolean | false untuk fail yang dimuat naik |
Permintaan muat naik
| Bahagian | Diperlukan | Penerangan |
|---|---|---|
file | Ya | Fail itu, dihantar sebagai bahagian fail multipart/form-data dengan nama fail |
Respons menyertakan pengepala Location dengan URL metadata fail.
Parameter senarai
| Parameter | Lalai | Penerangan |
|---|---|---|
limit | 100 | Saiz halaman, dari 1 hingga 1000 |
cursor | Nilai cursor daripada halaman sebelumnya | |
after, after_id | Alias bagi cursor. Hantar satu sahaja daripada ketiga-tiganya | |
order | asc | Hanya asc disokong |
| Medan respons | Jenis | Penerangan |
|---|---|---|
data | array | Objek fail, bermula daripada yang paling lama |
first_id | string atau null | ID fail pertama pada halaman |
last_id | string atau null | ID fail terakhir pada halaman |
cursor | string atau null | Nilai untuk dihantar sebagai cursor bagi halaman seterusnya |
has_more | boolean | Sama ada halaman lain wujud |
Ralat
Endpoint Files, Responses, serta penjanaan imej dan video menggunakan sampul ralat 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 ialah null untuk ralat daripada endpoint Files. Messages mengembalikan bentuk ralat Anthropic, yang tidak mempunyai error.code. ID permintaan berada dalam pengepala respons X-Request-Id.
Ralat semasa memuat naik atau mengurus fail:
| HTTP | error.code | Maksud |
|---|---|---|
| 400 | invalid_content_type | Badan bukan multipart/form-data |
| 400 | invalid_file | Tiada bahagian file, ada bahagian tambahan, fail kosong, atau kandungan tidak disokong |
| 400 | invalid_filename | Nama fail terlalu panjang atau mengandungi aksara yang ditolak |
| 413 | file_too_large | Fail melebihi 100 MiB |
| 400 | invalid_query | Parameter pertanyaan yang tidak disokong, atau order selain asc |
| 400 | invalid_limit | limit di luar julat 1 hingga 1000 |
| 400 | invalid_cursor | Format kursor tidak betul, atau lebih daripada satu kursor dihantar |
| 400 | file_not_downloadable | /content diminta |
| 404 | file_not_found | Fail tidak wujud, telah dipadam, atau milik akaun lain |
| 503 | file_storage_unavailable | Storan fail tidak tersedia buat sementara waktu; cuba semula kemudian |
| 503 | file_upload_expired | Muat naik tidak selesai dalam masa yang ditetapkan; muat naik fail sekali lagi |
Ralat semasa merujuk fail dalam permintaan model:
| HTTP | error.code | Maksud |
|---|---|---|
| 400 | invalid_file_input | Format ID tidak betul, file_id dan url kedua-duanya dalam satu locator, atau lebih daripada 100 rujukan |
| 400 | unsupported_file_type | Jenis fail tidak sepadan dengan kedudukannya, contohnya MP4 dalam blok dokumen |
| 400 | file_model_unsupported | Model tidak mengisytiharkan modaliti input yang diperlukan |
| 400 | file_input_too_large | Fail yang dirujuk melebihi 50,000,000 bait secara keseluruhan |
| 400 | file_protocol_unsupported | ID fail dihantar ke Chat Completions |
| 404 | file_not_found | Fail tiada, telah dipadam, dimiliki akaun lain, atau merupakan fail dijana yang dihantar ke penjanaan imej atau video |
Bagi penjanaan imej dan video, fail juga boleh gagal selepas 202. Tugasan kemudiannya berakhir sebagai failed dengan salah satu kod ini dalam error.code.
Ralat pengesahan, baki, dan had kadar diterangkan dalam Ralat, Had, dan Cuba Semula.
Berkaitan
Perlukan bantuan?
- Ada soalan tentang API, bil atau akaun? Hubungi sokongan.
- Berbual dengan pembangun Felo di Discord.
- Lihat log perubahan kami.
- Perlukan harga pukal atau bantuan perolehan? Hubungi jualan.
- Sedang membina dengan LLM? Baca llms.txt.