מדריכים
העלאת קבצים
העלו קובץ פעם אחת, ולאחר מכן הפנו אליו לפי מזהה (ID) בבקשות Messages, Responses, יצירת תמונות ויצירת וידאו.
העלו קובץ פעם אחת, ולאחר מכן הפנו אליו לפי המזהה שלו בבקשות למודלים. כך אין צורך לשלוח שוב את אותם בייטים כ-base64 או לארח את הקובץ בכתובת URL ציבורית.
מזהה קובץ עובד עם Messages, Responses, יצירת תמונות ויצירת וידאו. הוא אינו עובד עם Chat Completions.
לפני שמתחילים
- מפתח API. ראו אימות.
- כתובת הבסיס
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. - תנו ללקוח ה-HTTP שלכם להגדיר את
Content-Type. הגדרה ידנית שלו משמיטה את ה-multipart boundary. - אל תוסיפו פרמטרי שאילתה לכתובת ההעלאה.
- העלו דרך HTTP ולא דרך עוזר ה-Files של SDK.
files.create()של OpenAI SDK שולח תמידpurpose, ולכן אינו יכול לקרוא לנקודת הקצה הזו. - ייתכן שהעלאה שפג זמנה או שהתנתקה נשמרה בכל זאת. הציגו את רשימת הקבצים שלכם לפני שאתם מעלים שוב.
היכן אפשר להשתמש במזהה קובץ
| נקודת קצה | סוגי קבצים | מודאליות קלט נדרשת | שדה |
|---|---|---|---|
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 חייב לכלול |
|---|---|
| קובץ PDF | file |
| תמונה | image |
| קובץ MP4 | video |
| קובץ אודיו | audio |
רשימה ריקה או חסרה פירושה שמזהי קבצים אינם מופעלים עבור המודל הזה. הבקשה נכשלת אז עם 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 בחשבון רואה את אותם קבצים; חשבונות אחרים אינם יכולים להשתמש במזהי הקבצים שלכם.
הצגת רשימת קבצים
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 של המשימה.
הפניה ל-API
כל נקודות הקצה משתמשות ב-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 | מזהה הקובץ, עם הקידומת 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 עם שם קובץ |
התגובה כוללת כותרת Location עם כתובת ה-URL של המטא-נתונים של הקובץ.
פרמטרי הרשימה
| פרמטר | ברירת מחדל | תיאור |
|---|---|---|
limit | 100 | גודל העמוד, מ-1 עד 1000 |
cursor | ערך ה-cursor מהעמוד הקודם | |
after, after_id | כינויים של cursor. שלחו רק אחד מהשלושה | |
order | asc | רק asc נתמך |
| שדה תגובה | סוג | תיאור |
|---|---|---|
data | array | אובייקטי קובץ, מהישן לחדש |
first_id | string או null | מזהה הקובץ הראשון בעמוד |
last_id | string או null | מזהה הקובץ האחרון בעמוד |
cursor | string או null | הערך שיש להעביר כ-cursor עבור העמוד הבא |
has_more | boolean | האם קיים עמוד נוסף |
שגיאות
נקודות הקצה של הקבצים, 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 בשגיאות מנקודות הקצה של הקבצים. Messages מחזיר את מבנה השגיאה של Anthropic, שאין בו error.code. מזהה הבקשה נמצא בכותרת התגובה 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 | מזהה פגום, גם 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 | מזהה קובץ נשלח ל-Chat Completions |
| 404 | file_not_found | הקובץ חסר, נמחק, שייך לחשבון אחר, או שהוא קובץ שנוצר ונשלח ליצירת תמונות או וידאו |
ביצירת תמונות ווידאו, קובץ יכול להיכשל גם אחרי ה-202. המשימה מסתיימת אז כ-failed עם אחד מהקודים האלה ב-error.code.
שגיאות אימות, יתרה ומגבלת קצב מתוארות בשגיאות, מגבלות וניסיונות חוזרים.
קשור
צריך עזרה?
- לשאלות על API, חיוב וחשבון, פנו לתמיכה.
- שוחחו עם מפתחי Felo ב-Discord.
- עיינו ביומן השינויים שלנו.
- צריכים תמחור לפי נפח או עזרה ברכש? צרו קשר עם המכירות.
- בונים עם LLM? קראו את llms.txt.