Hướng dẫn
Tải tệp lên
Tải tệp lên một lần, sau đó tham chiếu bằng ID trong các yêu cầu Messages, Responses, tạo hình ảnh và tạo video.
Tải tệp lên một lần, sau đó tham chiếu tệp bằng ID trong các yêu cầu gửi đến mô hình. Cách này thay cho việc gửi lại cùng các byte đó dưới dạng base64 hoặc lưu trữ tệp tại một URL công khai.
ID tệp dùng được với Messages, Responses, tạo hình ảnh và tạo video. ID tệp không dùng được với Chat Completions.
Trước khi bắt đầu
- Một khóa API. Xem Xác thực.
- Base URL
https://openapi.felo.ai. - Một mô hình chấp nhận loại tệp bạn định gửi. Xem Kiểm tra khả năng hỗ trợ của mô hình.
Bắt đầu nhanh
1. Tải tệp lên
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"Tải lên thành công trả về HTTP 200 kèm siêu dữ liệu của tệp:
{
"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
}Lưu lại id. Hãy coi nó là một chuỗi opaque: đừng tự tạo hay phân tích nó.
2. Tham chiếu tệp trong yêu cầu
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."}
]
}
]
}'Hai bước tương tự bằng 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())Và bằng Node.js 20 trở lên:
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");Quy tắc tải lên
- Phần thân là
multipart/form-datavới đúng một phần, có tênfile. Mọi phần khác, kể cảpurpose, đều bị từ chối vớiinvalid_file. - Hãy để HTTP client của bạn đặt
Content-Type. Đặt thủ công sẽ làm mất multipart boundary. - Không thêm tham số truy vấn vào URL tải lên.
- Tải lên qua HTTP thay vì dùng helper Files của SDK.
files.create()của OpenAI SDK luôn gửipurpose, nên không thể gọi endpoint này. - Một lần tải lên bị hết thời gian chờ hoặc ngắt kết nối vẫn có thể đã được lưu. Hãy liệt kê các tệp của bạn trước khi tải lên lại.
Nơi có thể dùng ID tệp
| Endpoint | Loại tệp | Dạng thức đầu vào bắt buộc | Trường |
|---|---|---|---|
POST /api/v1/messages | PDF, hình ảnh | file, image | messages[].content[] |
POST /api/v1/responses | PDF, hình ảnh | file, image | input[].content[] |
POST /api/v1/images/generations | Hình ảnh | image | input_references[] |
POST /api/v1/videos/generations | Hình ảnh | image | frame_images[] |
POST /api/v1/videos/generations | Hình ảnh, MP4, âm thanh | image, video, audio | input_references[] |
POST /api/v1/chat/completions | Không hỗ trợ |
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."}
]
}
]
}Với hình ảnh, hãy dùng {"type": "image", "source": {"type": "file", "file_id": "..."}}.
Responses
| Tệp | Khối nội dung |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Hình ảnh | {"type": "input_image", "file_id": "...", "detail": "auto"} |
Một khối có file_id không được đồng thời chứa URL hoặc dữ liệu base64.
Tạo hình ảnh
{
"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..."}}
]
}Phần còn lại của yêu cầu, phản hồi 202 và việc thăm dò được mô tả trong Tạo hình ảnh.
Tạo video
Khung hình đầu và khung hình cuối nằm trong 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..."}
}
]
}Thêm mục thứ hai với "frame_type": "last_frame" để có khung hình cuối. Khung hình cuối yêu cầu phải có khung hình đầu.
Tư liệu tham chiếu nằm trong input_references. Mỗi mục dùng bộ định vị khớp với loại phương tiện của nó:
{
"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"}}
]
}Mô hình chấp nhận những tổ hợp nào tùy thuộc vào mô hình và kênh. Không thể dùng frame_images và input_references trong cùng một yêu cầu.
Quy tắc bộ định vị
- Trong các yêu cầu hình ảnh và video, mỗi đối tượng
image_url,video_urlhoặcaudio_urlchứa đúng một trong hai trườngfile_idhoặcurl, và không có trường nào khác. - Một mảng có thể kết hợp các mục dùng
file_idvới các mục dùngurl. - Tạo hình ảnh và tạo video chỉ chấp nhận các tệp do bạn tải lên. Để dùng lại một hình ảnh đã tạo, hãy truyền
urlđầu ra của nó. - Yêu cầu có tham chiếu tệp sẽ không được chuyển sang kênh khác khi thất bại. Đừng thử lại trên kênh khác khi chưa kiểm tra lỗi.
- Giữ tệp cho đến khi mọi tác vụ tham chiếu tệp đó đạt trạng thái kết thúc. Xóa tệp sớm hơn có thể làm tác vụ thất bại.
Kiểm tra khả năng hỗ trợ của mô hình
Tệp đã lưu không tự động dùng được với mọi mô hình. Mô hình phải khai báo dạng thức đầu vào tương ứng trong danh mục công khai:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Để gửi | input_modalities phải bao gồm |
|---|---|
| Tệp PDF | file |
| Hình ảnh | image |
| Tệp MP4 | video |
| Tệp âm thanh | audio |
Danh sách trống hoặc bị thiếu nghĩa là ID tệp chưa được bật cho mô hình đó. Khi đó yêu cầu thất bại với file_model_unsupported. Đừng suy đoán khả năng hỗ trợ từ tên mô hình.
Giới hạn
| Giới hạn | Giá trị |
|---|---|
| Kích thước tải lên | 100 MiB (104,857,600 byte) mỗi tệp; tệp trống bị từ chối |
| Số byte được tham chiếu mỗi yêu cầu mô hình | Tổng cộng 50,000,000 byte |
| Số tham chiếu mỗi yêu cầu mô hình | 100 |
| Độ dài tên tệp | 255 ký tự |
Tham chiếu cùng một tệp hai lần được tính hai lần vào cả hai giới hạn của yêu cầu. Tệp có kích thước từ 50 MB đến 100 MiB có thể tải lên nhưng không thể tham chiếu trong yêu cầu mô hình. Mô hình hoặc kênh có thể áp dụng giới hạn thấp hơn.
Loại tệp
Loại tệp được nhận diện từ nội dung của tệp, không phải từ phần mở rộng hay Content-Type của phần đó.
| Loại | Định dạng | Có thể tham chiếu trong |
|---|---|---|
| Messages, Responses | ||
| Hình ảnh | PNG, JPEG, GIF, WebP | Messages, Responses, tạo hình ảnh, tạo video |
| Video | MP4 | Tạo video |
| Âm thanh | MP3, WAV, FLAC, OGG | Tạo video |
| Office | DOCX, XLSX, PPTX | Chỉ lưu trữ |
| Văn bản | Văn bản UTF-8, được lưu dưới dạng text/plain | Chỉ lưu trữ |
Mọi nội dung khác đều bị từ chối với invalid_file.
Tên tệp
Tên tệp không được chứa <, >, :, ", |, ?, *, \ hoặc ký tự điều khiển. / được phép dùng làm dấu phân cách, nhưng không được có đoạn trống, . và ...
Quản lý tệp
Tệp thuộc về tài khoản của bạn. Mọi khóa API trong tài khoản đều thấy cùng các tệp; các tài khoản khác không thể dùng ID tệp của bạn.
Liệt kê tệp
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
}Kết quả được sắp xếp từ cũ nhất đến mới nhất. Khi has_more là true, hãy truyền cursor được trả về để lấy trang tiếp theo. Không có tính năng tìm kiếm hay lọc theo loại ở phía máy chủ.
Lấy một tệp
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Xóa tệp
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"}Việc xóa có hiệu lực ngay lập tức và không thể hoàn tác. 503 nghĩa là việc xóa chưa hoàn tất; hãy gửi lại DELETE.
Tải xuống
Không thể tải xuống các tệp đã tải lên. GET /api/v1/files/{file_id}/content trả về 400 file_not_downloadable, và header Location của phản hồi tải lên trỏ đến siêu dữ liệu của tệp, không phải các byte của tệp. Hãy tự giữ bản sao của mọi thứ bạn tải lên.
Để tải xuống nội dung đa phương tiện đã tạo, hãy dùng các URL đã ký trong outputs của tác vụ.
Tham chiếu API
Mọi endpoint đều dùng Authorization: Bearer YOUR_API_KEY. Phản hồi thành công là đối tượng JSON thuần, không có lớp bao ngoài.
| Phương thức | Đường dẫn | Trả về |
|---|---|---|
POST | /api/v1/files | Đối tượng tệp |
GET | /api/v1/files | Một trang tệp |
GET | /api/v1/files/{file_id} | Đối tượng tệp |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST, DELETE và GET cho một tệp đơn lẻ từ chối mọi tham số truy vấn với invalid_query.
Đối tượng tệp
| Trường | Kiểu | Mô tả |
|---|---|---|
id | string | ID tệp, có tiền tố felo_file_. Dùng nó làm file_id |
type | string | Luôn là file |
source | string | upload cho tệp bạn tải lên, generated cho đầu ra của mô hình |
filename | string | Tên được gửi kèm khi tải lên |
mime_type | string | Loại được nhận diện từ nội dung |
size_bytes | integer | Kích thước tính bằng byte |
created_at | string | Dấu thời gian UTC theo ISO 8601 |
downloadable | boolean | false đối với tệp đã tải lên |
Yêu cầu tải lên
| Phần | Bắt buộc | Mô tả |
|---|---|---|
file | Có | Tệp, được gửi dưới dạng phần tệp multipart/form-data kèm tên tệp |
Phản hồi có header Location chứa URL siêu dữ liệu của tệp.
Tham số liệt kê
| Tham số | Mặc định | Mô tả |
|---|---|---|
limit | 100 | Kích thước trang, từ 1 đến 1000 |
cursor | Giá trị cursor từ trang trước | |
after, after_id | Bí danh của cursor. Chỉ gửi một trong ba | |
order | asc | Chỉ hỗ trợ asc |
| Trường phản hồi | Kiểu | Mô tả |
|---|---|---|
data | array | Các đối tượng tệp, cũ nhất trước |
first_id | string hoặc null | ID của tệp đầu tiên trên trang |
last_id | string hoặc null | ID của tệp cuối cùng trên trang |
cursor | string hoặc null | Giá trị cần truyền làm cursor cho trang tiếp theo |
has_more | boolean | Có còn trang khác hay không |
Lỗi
Các endpoint Files, Responses, tạo hình ảnh và tạo video dùng cấu trúc lỗi của 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 là null đối với lỗi từ các endpoint Files. Messages trả về dạng lỗi của Anthropic, không có error.code. Request ID nằm trong header phản hồi X-Request-Id.
Lỗi khi tải lên hoặc quản lý tệp:
| HTTP | error.code | Ý nghĩa |
|---|---|---|
| 400 | invalid_content_type | Phần thân không phải multipart/form-data |
| 400 | invalid_file | Không có phần file, có phần thừa, tệp trống hoặc nội dung không được hỗ trợ |
| 400 | invalid_filename | Tên tệp quá dài hoặc chứa ký tự bị từ chối |
| 413 | file_too_large | Tệp vượt quá 100 MiB |
| 400 | invalid_query | Tham số truy vấn không được hỗ trợ, hoặc order khác asc |
| 400 | invalid_limit | limit nằm ngoài khoảng 1 đến 1000 |
| 400 | invalid_cursor | Con trỏ sai định dạng, hoặc có nhiều hơn một con trỏ được gửi |
| 400 | file_not_downloadable | /content đã được yêu cầu |
| 404 | file_not_found | Tệp không tồn tại, đã bị xóa hoặc thuộc tài khoản khác |
| 503 | file_storage_unavailable | Lưu trữ tệp tạm thời không khả dụng; thử lại sau |
| 503 | file_upload_expired | Tải lên không hoàn tất kịp thời; hãy tải tệp lên lại |
Lỗi khi tham chiếu tệp trong yêu cầu mô hình:
| HTTP | error.code | Ý nghĩa |
|---|---|---|
| 400 | invalid_file_input | ID sai định dạng, có cả file_id và url trong một bộ định vị, hoặc nhiều hơn 100 tham chiếu |
| 400 | unsupported_file_type | Loại tệp không khớp với vị trí, ví dụ một tệp MP4 trong khối tài liệu |
| 400 | file_model_unsupported | Mô hình không khai báo dạng thức đầu vào bắt buộc |
| 400 | file_input_too_large | Các tệp được tham chiếu vượt quá tổng cộng 50,000,000 byte |
| 400 | file_protocol_unsupported | Một ID tệp đã được gửi đến Chat Completions |
| 404 | file_not_found | Tệp không tồn tại, đã bị xóa, thuộc tài khoản khác, hoặc là tệp được tạo sinh gửi đến tạo hình ảnh hoặc tạo video |
Với tạo hình ảnh và tạo video, tệp cũng có thể thất bại sau 202. Khi đó tác vụ kết thúc ở trạng thái failed với một trong các mã này trong error.code.
Lỗi xác thực, số dư và giới hạn tốc độ được mô tả trong Lỗi, giới hạn và thử lại.
Liên quan
Cần trợ giúp?
- Cần hỏi về API, thanh toán hoặc tài khoản? Liên hệ bộ phận hỗ trợ.
- Trò chuyện với đội ngũ phát triển Felo trên Discord.
- Xem nhật ký thay đổi của chúng tôi.
- Cần báo giá theo số lượng lớn hoặc hỗ trợ mua hàng? Liên hệ kinh doanh.
- Bạn đang xây dựng với LLM? Đọc llms.txt.