Felo API PlatformFelo API Platform

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

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-data với đúng một phần, có tên file. Mọi phần khác, kể cả purpose, đều bị từ chối với invalid_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ửi purpose, 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

EndpointLoại tệpDạng thức đầu vào bắt buộcTrường
POST /api/v1/messagesPDF, hình ảnhfile, imagemessages[].content[]
POST /api/v1/responsesPDF, hình ảnhfile, imageinput[].content[]
POST /api/v1/images/generationsHình ảnhimageinput_references[]
POST /api/v1/videos/generationsHình ảnhimageframe_images[]
POST /api/v1/videos/generationsHình ảnh, MP4, âm thanhimage, video, audioinput_references[]
POST /api/v1/chat/completionsKhô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ệpKhối nội dung
PDF{"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_url hoặc audio_url chứa đúng một trong hai trường file_id hoặc url, 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_id với các mục dùng url.
  • 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ửiinput_modalities phải bao gồm
Tệp PDFfile
Hình ảnhimage
Tệp MP4video
Tệp âm thanhaudio

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ạnGiá trị
Kích thước tải lên100 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ìnhTổng cộng 50,000,000 byte
Số tham chiếu mỗi yêu cầu mô hình100
Độ dài tên tệp255 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ạngCó thể tham chiếu trong
PDFPDFMessages, Responses
Hình ảnhPNG, JPEG, GIF, WebPMessages, Responses, tạo hình ảnh, tạo video
VideoMP4Tạo video
Âm thanhMP3, WAV, FLAC, OGGTạo video
OfficeDOCX, XLSX, PPTXChỉ lưu trữ
Văn bảnVăn bản UTF-8, được lưu dưới dạng text/plainChỉ 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ẫnTrả về
POST/api/v1/filesĐối tượng tệp
GET/api/v1/filesMộ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}/content400 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ườngKiểuMô tả
idstringID tệp, có tiền tố felo_file_. Dùng nó làm file_id
typestringLuôn là file
sourcestringupload cho tệp bạn tải lên, generated cho đầu ra của mô hình
filenamestringTên được gửi kèm khi tải lên
mime_typestringLoại được nhận diện từ nội dung
size_bytesintegerKích thước tính bằng byte
created_atstringDấu thời gian UTC theo ISO 8601
downloadablebooleanfalse đối với tệp đã tải lên

Yêu cầu tải lên

PhầnBắt buộcMô tả
fileCó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 địnhMô tả
limit100Kích thước trang, từ 1 đến 1000
cursorGiá trị cursor từ trang trước
after, after_idBí danh của cursor. Chỉ gửi một trong ba
orderascChỉ hỗ trợ asc
Trường phản hồiKiểuMô tả
dataarrayCác đối tượng tệp, cũ nhất trước
first_idstring hoặc nullID của tệp đầu tiên trên trang
last_idstring hoặc nullID của tệp cuối cùng trên trang
cursorstring hoặc nullGiá trị cần truyền làm cursor cho trang tiếp theo
has_morebooleanCó 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:

HTTPerror.codeÝ nghĩa
400invalid_content_typePhần thân không phải multipart/form-data
400invalid_fileKhông có phần file, có phần thừa, tệp trống hoặc nội dung không được hỗ trợ
400invalid_filenameTên tệp quá dài hoặc chứa ký tự bị từ chối
413file_too_largeTệp vượt quá 100 MiB
400invalid_queryTham số truy vấn không được hỗ trợ, hoặc order khác asc
400invalid_limitlimit nằm ngoài khoảng 1 đến 1000
400invalid_cursorCon trỏ sai định dạng, hoặc có nhiều hơn một con trỏ được gửi
400file_not_downloadable/content đã được yêu cầu
404file_not_foundTệp không tồn tại, đã bị xóa hoặc thuộc tài khoản khác
503file_storage_unavailableLưu trữ tệp tạm thời không khả dụng; thử lại sau
503file_upload_expiredTả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:

HTTPerror.codeÝ nghĩa
400invalid_file_inputID 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
400unsupported_file_typeLoạ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
400file_model_unsupportedMô hình không khai báo dạng thức đầu vào bắt buộc
400file_input_too_largeCác tệp được tham chiếu vượt quá tổng cộng 50,000,000 byte
400file_protocol_unsupportedMột ID tệp đã được gửi đến Chat Completions
404file_not_foundTệ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?