Felo API PlatformFelo API Platform

คู่มือ

การอัปโหลดไฟล์

อัปโหลดไฟล์ครั้งเดียว แล้วอ้างอิงด้วย ID ในคำขอ Messages, Responses, การสร้างภาพ และการสร้างวิดีโอ

อัปโหลดไฟล์ครั้งเดียว แล้วอ้างอิงด้วย ID ในคำขอไปยังโมเดล วิธีนี้ใช้แทนการส่งไบต์ชุดเดิมซ้ำเป็น base64 หรือการโฮสต์ไฟล์ไว้ที่ URL สาธารณะ

ID ไฟล์ใช้ได้กับ Messages, Responses, การสร้างรูปภาพ และการสร้างวิดีโอ แต่ใช้กับ Chat Completions ไม่ได้

ก่อนเริ่มต้น

เริ่มต้นอย่างรวดเร็ว

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/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 ทุกคีย์ในบัญชีเห็นไฟล์ชุดเดียวกัน บัญชีอื่นใช้ 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}/content400 file_not_downloadable

POST, DELETE และ GET แบบไฟล์เดียวปฏิเสธพารามิเตอร์คิวรีทุกตัวด้วย invalid_query

ออบเจกต์ไฟล์

ฟิลด์ชนิดคำอธิบาย
idstringID ไฟล์ ขึ้นต้นด้วย felo_file_ ใช้เป็น file_id
typestringเป็น file เสมอ
sourcestringupload สำหรับไฟล์ที่คุณอัปโหลด generated สำหรับเอาต์พุตของโมเดล
filenamestringชื่อที่ส่งมากับการอัปโหลด
mime_typestringประเภทที่ตรวจจับจากเนื้อหา
size_bytesintegerขนาดเป็นไบต์
created_atstringไทม์สแตมป์ UTC แบบ ISO 8601
downloadablebooleanfalse สำหรับไฟล์ที่อัปโหลด

คำขออัปโหลด

ส่วนจำเป็นคำอธิบาย
fileใช่ตัวไฟล์ ส่งเป็นส่วนไฟล์ของ multipart/form-data พร้อมชื่อไฟล์

การตอบกลับมี header Location ที่ระบุ URL ของเมทาดาทาของไฟล์

พารามิเตอร์การแสดงรายการ

พารามิเตอร์ค่าเริ่มต้นคำอธิบาย
limit100ขนาดหน้า ตั้งแต่ 1 ถึง 1000
cursorค่า cursor จากหน้าก่อนหน้า
after, after_idชื่อแทนของ cursor ส่งได้เพียงหนึ่งในสามตัวนี้
orderascรองรับเฉพาะ asc
ฟิลด์การตอบกลับชนิดคำอธิบาย
dataarrayออบเจกต์ไฟล์ เรียงจากเก่าที่สุดก่อน
first_idstring หรือ nullID ของไฟล์แรกในหน้า
last_idstring หรือ nullID ของไฟล์สุดท้ายในหน้า
cursorstring หรือ nullค่าที่ส่งเป็น cursor สำหรับหน้าถัดไป
has_morebooleanมีหน้าถัดไปหรือไม่

ข้อผิดพลาด

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

ข้อผิดพลาดเมื่ออัปโหลดหรือจัดการไฟล์:

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ส่ง ID ไฟล์ไปยัง Chat Completions
404file_not_foundไฟล์ไม่มีอยู่ ถูกลบแล้ว เป็นของบัญชีอื่น หรือเป็นไฟล์ที่สร้างขึ้นซึ่งถูกส่งไปยังการสร้างรูปภาพหรือวิดีโอ

สำหรับการสร้างรูปภาพและวิดีโอ ไฟล์อาจล้มเหลวหลัง 202 ได้เช่นกัน งานจะสิ้นสุดเป็น failed โดยมีรหัสข้างต้นรหัสใดรหัสหนึ่งใน error.code

ข้อผิดพลาดด้านการรับรองความถูกต้อง ยอดคงเหลือ และขีดจำกัดอัตราอธิบายไว้ในข้อผิดพลาด ขีดจำกัด และการลองใหม่

เนื้อหาที่เกี่ยวข้อง

ต้องการความช่วยเหลือไหม