Felo API PlatformFelo API Platform

מדריכים

העלאת קבצים

העלו קובץ פעם אחת, ולאחר מכן הפנו אליו לפי מזהה (ID) בבקשות Messages, Responses, יצירת תמונות ויצירת וידאו.

העלו קובץ פעם אחת, ולאחר מכן הפנו אליו לפי המזהה שלו בבקשות למודלים. כך אין צורך לשלוח שוב את אותם בייטים כ-base64 או לארח את הקובץ בכתובת URL ציבורית.

מזהה קובץ עובד עם 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. התייחסו אליו כאל מחרוזת אטומה: אל תבנו אותו ואל תנתחו אותו.

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/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

רשימה ריקה או חסרה פירושה שמזהי קבצים אינם מופעלים עבור המודל הזה. הבקשה נכשלת אז עם 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 בחשבון רואה את אותם קבצים; חשבונות אחרים אינם יכולים להשתמש במזהי הקבצים שלכם.

הצגת רשימת קבצים

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}/content400 file_not_downloadable

POST, DELETE ו-GET של קובץ יחיד דוחים כל פרמטר שאילתה עם invalid_query.

אובייקט הקובץ

שדהסוגתיאור
idstringמזהה הקובץ, עם הקידומת felo_file_. השתמשו בו כ-file_id
typestringתמיד file
sourcestringupload לקבצים שהעליתם, generated לפלטי מודל
filenamestringהשם שנשלח עם ההעלאה
mime_typestringהסוג שזוהה מהתוכן
size_bytesintegerהגודל בבייטים
created_atstringחותמת זמן UTC בפורמט ISO 8601
downloadablebooleanfalse לקבצים שהועלו

בקשת העלאה

חלקחובהתיאור
fileכןהקובץ, נשלח כחלק קובץ של multipart/form-data עם שם קובץ

התגובה כוללת כותרת Location עם כתובת ה-URL של המטא-נתונים של הקובץ.

פרמטרי הרשימה

פרמטרברירת מחדלתיאור
limit100גודל העמוד, מ-1 עד 1000
cursorערך ה-cursor מהעמוד הקודם
after, after_idכינויים של cursor. שלחו רק אחד מהשלושה
orderascרק asc נתמך
שדה תגובהסוגתיאור
dataarrayאובייקטי קובץ, מהישן לחדש
first_idstring או nullמזהה הקובץ הראשון בעמוד
last_idstring או nullמזהה הקובץ האחרון בעמוד
cursorstring או nullהערך שיש להעביר כ-cursor עבור העמוד הבא
has_morebooleanהאם קיים עמוד נוסף

שגיאות

נקודות הקצה של הקבצים, 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.

שגיאות בעת העלאה או ניהול של קבצים:

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_inputמזהה פגום, גם file_id וגם url במאתר אחד, או יותר מ-100 הפניות
400unsupported_file_typeסוג הקובץ אינו תואם למיקום, למשל MP4 בבלוק מסמך
400file_model_unsupportedהמודל אינו מצהיר על מודאליות הקלט הנדרשת
400file_input_too_largeהקבצים שאליהם מפנים חורגים מ-50,000,000 בייטים בסך הכול
400file_protocol_unsupportedמזהה קובץ נשלח ל-Chat Completions
404file_not_foundהקובץ חסר, נמחק, שייך לחשבון אחר, או שהוא קובץ שנוצר ונשלח ליצירת תמונות או וידאו

ביצירת תמונות ווידאו, קובץ יכול להיכשל גם אחרי ה-202. המשימה מסתיימת אז כ-failed עם אחד מהקודים האלה ב-error.code.

שגיאות אימות, יתרה ומגבלת קצב מתוארות בשגיאות, מגבלות וניסיונות חוזרים.

קשור

צריך עזרה?