Felo API PlatformFelo API Platform

指南

檔案上傳

檔案上傳一次,之後在 Messages、Responses、圖片生成和影片生成請求中以 ID 引用。

檔案上傳一次,之後在模型請求中按 ID 引用,不必每次把同一份內容轉成 base64 重送,也不必把檔案放到公開 URL 上。

檔案 ID 可用於 Messages、Responses、圖片生成和影片生成,不能用於 Chat Completions。

開始之前

  • API key。見認證。
  • Base URL:https://openapi.felo.ai。
  • 一個接受對應檔案類型的模型。見檢查模型支援。

快速開始

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/messagesPDF、圖片file、imagemessages[].content[]
POST /api/v1/responsesPDF、圖片file、imageinput[].content[]
POST /api/v1/images/generations圖片imageinput_references[]
POST /api/v1/videos/generations圖片imageframe_images[]
POST /api/v1/videos/generations圖片、MP4、音訊image、video、audioinput_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

檔案內容區塊
PDF{"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 必須包含
PDFfile
圖片image
MP4video
音訊檔audio

列表為空或不存在,表示該模型尚未啟用檔案 ID,請求會以 file_model_unsupported 失敗。不要根據模型名稱推斷是否支援。

限制

限制值
上傳大小單一檔案 100 MiB(104,857,600 位元組);空檔案會被拒絕
單次模型請求引用的位元組數合計 50,000,000 位元組
單次模型請求的引用次數100
檔名長度255 個字元

同一檔案引用兩次,兩項請求限制都按兩次計。50 MB 到 100 MiB 之間的檔案可以上傳,但不能在模型請求中引用。模型或通道的限制可能更低。

檔案類型

類型依檔案內容偵測,不看副檔名,也不看該部分的 Content-Type。

類型格式可以引用的位置
PDFPDFMessages、Responses
圖片PNG、JPEG、GIF、WebPMessages、Responses、圖片生成、影片生成
影片MP4影片生成
音訊MP3、WAV、FLAC、OGG影片生成
OfficeDOCX、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}/content400 file_not_downloadable

POST、DELETE 和單一檔案的 GET 帶任何查詢參數都會以 invalid_query 拒絕。

檔案物件

欄位類型說明
idstring檔案 ID,以 felo_file_ 開頭,用作 file_id
typestring固定為 file
sourcestringupload 表示你上傳的檔案,generated 表示模型輸出
filenamestring上傳時傳送的檔名
mime_typestring依內容偵測出的類型
size_bytesinteger大小,單位為位元組
created_atstringISO 8601 UTC 時間戳記
downloadableboolean上傳的檔案為 false

上傳請求

部分必填說明
file是檔案本身,作為 multipart/form-data 的檔案部分傳送,並帶檔名

回應帶有 Location 標頭,值為該檔案中繼資料的 URL。

列表參數

參數預設值說明
limit100每頁數量,1 到 1000
cursor上一頁回傳的 cursor 值
after、after_idcursor 的別名。三者只能傳一個
orderasc只支援 asc
回應欄位類型說明
dataarray檔案物件,從舊到新
first_idstring 或 null本頁第一個檔案的 ID
last_idstring 或 null本頁最後一個檔案的 ID
cursorstring 或 null取得下一頁時作為 cursor 傳入的值
has_moreboolean是否還有下一頁

錯誤

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 回應標頭裡。

上傳和管理檔案時的錯誤:

HTTPerror.code含義
400invalid_content_type請求主體不是 multipart/form-data
400invalid_file缺少 file 部分、有多餘的部分、檔案為空,或內容不受支援
400invalid_filename檔名過長,或包含不允許的字元
413file_too_large檔案超過 100 MiB
400invalid_query帶了不支援的查詢參數,或 order 不是 asc
400invalid_limitlimit 不在 1 到 1000 之間
400invalid_cursor游標格式錯誤,或同時傳了多個游標
400file_not_downloadable請求了 /content
404file_not_found檔案不存在、已刪除,或屬於其他帳號
503file_storage_unavailable檔案儲存暫時不可用;稍後重試
503file_upload_expired上傳沒有在時限內完成;請重新上傳檔案

在模型請求中引用檔案時的錯誤:

HTTPerror.code含義
400invalid_file_inputID 格式錯誤、同一個定位物件裡同時有 file_id 和 url,或引用超過 100 次
400unsupported_file_type檔案類型與所在位置不符,例如把 MP4 放進文件區塊
400file_model_unsupported模型沒有宣告所需的輸入模態
400file_input_too_large引用的檔案合計超過 50,000,000 位元組
400file_protocol_unsupported向 Chat Completions 傳送了檔案 ID
404file_not_found檔案不存在、已刪除、屬於其他帳號,或把生成的檔案傳給圖片或影片生成

在圖片和影片生成中,檔案也可能在回傳 202 之後才失敗。此時任務會以 failed 結束,error.code 為上述代碼之一。

認證、餘額和限流錯誤見錯誤、限流與重試。

相關

需要協助嗎?