คู่มือ
การอัปโหลดไฟล์
อัปโหลดไฟล์ครั้งเดียว แล้วอ้างอิงด้วย ID ในคำขอ Messages, Responses, การสร้างภาพ และการสร้างวิดีโอ
อัปโหลดไฟล์ครั้งเดียว แล้วอ้างอิงด้วย ID ในคำขอไปยังโมเดล วิธีนี้ใช้แทนการส่งไบต์ชุดเดิมซ้ำเป็น base64 หรือการโฮสต์ไฟล์ไว้ที่ URL สาธารณะ
ID ไฟล์ใช้ได้กับ Messages, Responses, การสร้างรูปภาพ และการสร้างวิดีโอ แต่ใช้กับ Chat Completions ไม่ได้
ก่อนเริ่มต้น
- คีย์ API ดูการรับรองความถูกต้อง
- 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 ไว้ ให้ถือว่าเป็นสตริงแบบ opaque: อย่าสร้างหรือแยกวิเคราะห์เอง
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 - ให้ไคลเอนต์ HTTP ตั้งค่า
Content-Typeเอง การตั้งค่าด้วยมือจะทำให้ multipart boundary หายไป - อย่าเพิ่มพารามิเตอร์คิวรีต่อท้าย URL อัปโหลด
- อัปโหลดผ่าน HTTP แทนการใช้ตัวช่วย Files ของ SDK เพราะ
files.create()ของ OpenAI SDK ส่ง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 ทุกคีย์ในบัญชีเห็นไฟล์ชุดเดียวกัน บัญชีอื่นใช้ 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 และ header Location ของการตอบกลับการอัปโหลดชี้ไปยังเมทาดาทาของไฟล์ ไม่ใช่ไบต์ของไฟล์ ให้เก็บสำเนาของทุกอย่างที่คุณอัปโหลดไว้เอง
หากต้องการดาวน์โหลดสื่อที่สร้างขึ้น ให้ใช้ URL ที่ลงนามใน outputs ของงาน
เอกสารอ้างอิง 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 | ไทม์สแตมป์ UTC แบบ ISO 8601 |
downloadable | boolean | false สำหรับไฟล์ที่อัปโหลด |
คำขออัปโหลด
| ส่วน | จำเป็น | คำอธิบาย |
|---|---|---|
file | ใช่ | ตัวไฟล์ ส่งเป็นส่วนไฟล์ของ multipart/form-data พร้อมชื่อไฟล์ |
การตอบกลับมี header 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 | มีหน้าถัดไปหรือไม่ |
ข้อผิดพลาด
endpoint ของ Files, 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"
}
}param เป็น null สำหรับข้อผิดพลาดจาก endpoint ของ Files ส่วน Messages ส่งรูปแบบข้อผิดพลาดของ Anthropic ซึ่งไม่มี error.code request ID อยู่ใน header การตอบกลับ 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 | ส่ง ID ไฟล์ไปยัง Chat Completions |
| 404 | file_not_found | ไฟล์ไม่มีอยู่ ถูกลบแล้ว เป็นของบัญชีอื่น หรือเป็นไฟล์ที่สร้างขึ้นซึ่งถูกส่งไปยังการสร้างรูปภาพหรือวิดีโอ |
สำหรับการสร้างรูปภาพและวิดีโอ ไฟล์อาจล้มเหลวหลัง 202 ได้เช่นกัน งานจะสิ้นสุดเป็น failed โดยมีรหัสข้างต้นรหัสใดรหัสหนึ่งใน error.code
ข้อผิดพลาดด้านการรับรองความถูกต้อง ยอดคงเหลือ และขีดจำกัดอัตราอธิบายไว้ในข้อผิดพลาด ขีดจำกัด และการลองใหม่
เนื้อหาที่เกี่ยวข้อง
ต้องการความช่วยเหลือไหม
- หากมีคำถามเรื่อง API การเรียกเก็บเงิน หรือบัญชี ติดต่อฝ่ายสนับสนุน
- พูดคุยกับนักพัฒนา Felo บน Discord
- ดูบันทึกการเปลี่ยนแปลงของเรา
- ต้องการราคาตามปริมาณหรือความช่วยเหลือด้านการจัดซื้อ? ติดต่อฝ่ายขาย
- กำลังสร้างด้วย LLM อยู่หรือไม่ อ่าน llms.txt