指南
檔案上傳
檔案上傳一次,之後在 Messages、Responses、圖片生成和影片生成請求中以 ID 引用。
檔案上傳一次,之後在模型請求中按 ID 引用,不必每次把同一份內容轉成 base64 重送,也不必把檔案放到公開 URL 上。
檔案 ID 可用於 Messages、Responses、圖片生成和影片生成,不能用於 Chat Completions。
開始之前
快速開始
1. 上傳檔案
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"上傳成功會回傳 HTTP 200 和檔案的中繼資料:
{
"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。把它當作不透明字串使用,不要自行組合或解析。
2. 在請求中引用
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."}
]
}
]
}'同樣的兩步,用 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())用 Node.js 20 或更新版本:
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");上傳規則
- 請求主體是
multipart/form-data,只能有一個名為file的部分。附帶其他部分(包括purpose)會回傳invalid_file。 Content-Type交給 HTTP 用戶端產生。手動設定會遺失 multipart boundary。- 上傳 URL 不要帶查詢參數。
- 直接用 HTTP 上傳,不要用 SDK 的 Files 方法。OpenAI SDK 的
files.create()一律會附帶purpose,無法呼叫這個 endpoint。 - 上傳逾時或連線中斷時,檔案可能已經儲存。重新上傳前先查看檔案列表。
檔案 ID 可以放在哪裡
| Endpoint | 檔案類型 | 需要的輸入模態 | 欄位 |
|---|---|---|---|
POST /api/v1/messages | PDF、圖片 | file、image | messages[].content[] |
POST /api/v1/responses | PDF、圖片 | file、image | input[].content[] |
POST /api/v1/images/generations | 圖片 | image | input_references[] |
POST /api/v1/videos/generations | 圖片 | image | frame_images[] |
POST /api/v1/videos/generations | 圖片、MP4、音訊 | image、video、audio | input_references[] |
POST /api/v1/chat/completions | 不支援 |
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."}
]
}
]
}圖片使用 {"type": "image", "source": {"type": "file", "file_id": "..."}}。
Responses
| 檔案 | 內容區塊 |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| 圖片 | {"type": "input_image", "file_id": "...", "detail": "auto"} |
帶 file_id 的內容區塊不能同時帶 URL 或 base64 資料。
圖片生成
{
"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..."}}
]
}請求的其餘部分、202 回應和輪詢見圖片生成。
影片生成
首幀和尾幀放在 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..."}
}
]
}需要尾幀時,再加一項 "frame_type": "last_frame"。有尾幀就必須有首幀。
參考素材放在 input_references,每一項使用與媒體類型對應的定位物件:
{
"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"}}
]
}模型接受哪些組合取決於模型和通道。frame_images 與 input_references 不能用在同一個請求裡。
定位規則
- 圖片和影片請求中,每個
image_url、video_url、audio_url物件只能有file_id或url其中一個欄位,不能有其他欄位。 - 同一個陣列裡,可以有的項目用
file_id,有的項目用url。 - 圖片和影片生成只接受你自己上傳的檔案。要重複使用生成的圖片,請傳它的輸出
url。 - 引用了檔案的請求失敗後不會切換到其他通道。先確認錯誤原因,不要直接換通道重試。
- 引用該檔案的任務全部進入終態前,請保留檔案。提前刪除可能導致任務失敗。
檢查模型支援
檔案上傳成功,不代表所有模型都能使用它。模型必須在公開目錄中宣告對應的輸入模態:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| 要傳送 | input_modalities 必須包含 |
|---|---|
file | |
| 圖片 | image |
| MP4 | video |
| 音訊檔 | audio |
列表為空或不存在,表示該模型尚未啟用檔案 ID,請求會以 file_model_unsupported 失敗。不要根據模型名稱推斷是否支援。
限制
| 限制 | 值 |
|---|---|
| 上傳大小 | 單一檔案 100 MiB(104,857,600 位元組);空檔案會被拒絕 |
| 單次模型請求引用的位元組數 | 合計 50,000,000 位元組 |
| 單次模型請求的引用次數 | 100 |
| 檔名長度 | 255 個字元 |
同一檔案引用兩次,兩項請求限制都按兩次計。50 MB 到 100 MiB 之間的檔案可以上傳,但不能在模型請求中引用。模型或通道的限制可能更低。
檔案類型
類型依檔案內容偵測,不看副檔名,也不看該部分的 Content-Type。
| 類型 | 格式 | 可以引用的位置 |
|---|---|---|
| Messages、Responses | ||
| 圖片 | PNG、JPEG、GIF、WebP | Messages、Responses、圖片生成、影片生成 |
| 影片 | MP4 | 影片生成 |
| 音訊 | MP3、WAV、FLAC、OGG | 影片生成 |
| Office | DOCX、XLSX、PPTX | 僅儲存 |
| 文字 | UTF-8 文字,以 text/plain 儲存 | 僅儲存 |
其他內容會以 invalid_file 拒絕。
檔名
檔名不能包含 <、>、:、"、|、?、*、\ 和控制字元。可以用 / 作為分隔符號,但不能有空區段、. 或 ..。
管理檔案
檔案屬於你的帳號。同一帳號下的所有 API key 看到的是同一批檔案;其他帳號不能使用你的檔案 ID。
列出檔案
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
}結果從舊到新排列。has_more 為 true 時,傳入回傳的 cursor 取得下一頁。伺服器端不提供搜尋或依類型篩選。
取得單一檔案
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"刪除檔案
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"}刪除立即生效,無法復原。回傳 503 表示刪除沒有完成,請重新傳送 DELETE。
下載
上傳的檔案不能下載。GET /api/v1/files/{file_id}/content 回傳 400 file_not_downloadable;上傳回應的 Location 標頭指向檔案的中繼資料,不是檔案內容。上傳的內容請自行保留副本。
要下載生成的媒體,請使用任務 outputs 中的簽名 URL。
API 參考
所有 endpoint 都使用 Authorization: Bearer YOUR_API_KEY。成功回應就是 JSON 物件本身,沒有外層信封。
| 方法 | 路徑 | 回傳 |
|---|---|---|
POST | /api/v1/files | 檔案物件 |
GET | /api/v1/files | 一頁檔案 |
GET | /api/v1/files/{file_id} | 檔案物件 |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST、DELETE 和單一檔案的 GET 帶任何查詢參數都會以 invalid_query 拒絕。
檔案物件
| 欄位 | 類型 | 說明 |
|---|---|---|
id | string | 檔案 ID,以 felo_file_ 開頭,用作 file_id |
type | string | 固定為 file |
source | string | upload 表示你上傳的檔案,generated 表示模型輸出 |
filename | string | 上傳時傳送的檔名 |
mime_type | string | 依內容偵測出的類型 |
size_bytes | integer | 大小,單位為位元組 |
created_at | string | ISO 8601 UTC 時間戳記 |
downloadable | boolean | 上傳的檔案為 false |
上傳請求
| 部分 | 必填 | 說明 |
|---|---|---|
file | 是 | 檔案本身,作為 multipart/form-data 的檔案部分傳送,並帶檔名 |
回應帶有 Location 標頭,值為該檔案中繼資料的 URL。
列表參數
| 參數 | 預設值 | 說明 |
|---|---|---|
limit | 100 | 每頁數量,1 到 1000 |
cursor | 上一頁回傳的 cursor 值 | |
after、after_id | cursor 的別名。三者只能傳一個 | |
order | asc | 只支援 asc |
| 回應欄位 | 類型 | 說明 |
|---|---|---|
data | array | 檔案物件,從舊到新 |
first_id | string 或 null | 本頁第一個檔案的 ID |
last_id | string 或 null | 本頁最後一個檔案的 ID |
cursor | string 或 null | 取得下一頁時作為 cursor 傳入的值 |
has_more | boolean | 是否還有下一頁 |
錯誤
Files endpoint、Responses、圖片生成和影片生成使用 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"
}
}Files endpoint 回傳的錯誤,param 為 null。Messages 回傳 Anthropic 的錯誤格式,沒有 error.code。request ID 在 X-Request-Id 回應標頭裡。
上傳和管理檔案時的錯誤:
| HTTP | error.code | 含義 |
|---|---|---|
| 400 | invalid_content_type | 請求主體不是 multipart/form-data |
| 400 | invalid_file | 缺少 file 部分、有多餘的部分、檔案為空,或內容不受支援 |
| 400 | invalid_filename | 檔名過長,或包含不允許的字元 |
| 413 | file_too_large | 檔案超過 100 MiB |
| 400 | invalid_query | 帶了不支援的查詢參數,或 order 不是 asc |
| 400 | invalid_limit | limit 不在 1 到 1000 之間 |
| 400 | invalid_cursor | 游標格式錯誤,或同時傳了多個游標 |
| 400 | file_not_downloadable | 請求了 /content |
| 404 | file_not_found | 檔案不存在、已刪除,或屬於其他帳號 |
| 503 | file_storage_unavailable | 檔案儲存暫時不可用;稍後重試 |
| 503 | file_upload_expired | 上傳沒有在時限內完成;請重新上傳檔案 |
在模型請求中引用檔案時的錯誤:
| HTTP | error.code | 含義 |
|---|---|---|
| 400 | invalid_file_input | ID 格式錯誤、同一個定位物件裡同時有 file_id 和 url,或引用超過 100 次 |
| 400 | unsupported_file_type | 檔案類型與所在位置不符,例如把 MP4 放進文件區塊 |
| 400 | file_model_unsupported | 模型沒有宣告所需的輸入模態 |
| 400 | file_input_too_large | 引用的檔案合計超過 50,000,000 位元組 |
| 400 | file_protocol_unsupported | 向 Chat Completions 傳送了檔案 ID |
| 404 | file_not_found | 檔案不存在、已刪除、屬於其他帳號,或把生成的檔案傳給圖片或影片生成 |
在圖片和影片生成中,檔案也可能在回傳 202 之後才失敗。此時任務會以 failed 結束,error.code 為上述代碼之一。
認證、餘額和限流錯誤見錯誤、限流與重試。