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。

接口说明

所有 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 是上表中的某一项。

鉴权、余额和限流错误见错误、限流与重试。

相关

需要帮助?