# העלאת קבצים

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

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

מזהה קובץ עובד עם Messages, Responses, יצירת תמונות ויצירת וידאו. הוא אינו עובד עם Chat Completions.

## לפני שמתחילים

- מפתח API. ראו [אימות](https://openapi.felo.ai/he/docs/authentication.md).
- כתובת הבסיס `https://openapi.felo.ai`.
- מודל שמקבל את סוג הקובץ שאתם מתכוונים לשלוח. ראו [בדיקת תמיכת המודל](#section-8).

## התחלה מהירה

### 1. העלו את הקובץ

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

העלאה מוצלחת מחזירה HTTP `200` עם המטא-נתונים של הקובץ:

```json
{
  "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. הפנו אליו בבקשה

```bash
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:

```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 ומעלה:

```javascript
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

```json
{
  "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.

### יצירת תמונות

```json
{
  "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` והבדיקה החוזרת מתוארים ב[יצירת תמונות](https://openapi.felo.ai/he/docs/guides/image-generation.md).

### יצירת וידאו

הפריים הראשון והפריים האחרון נכנסים ל-`frame_images`:

```json
{
  "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`. כל פריט משתמש במאתר שמתאים לסוג המדיה שלו:

```json
{
  "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` של הפלט שלה.
- בקשה שמפנה לקובץ אינה מועברת לערוץ אחר בעת כשל. אל תנסו אותה שוב בערוץ אחר בלי לבדוק את השגיאה.
- שמרו קובץ עד שכל משימה שמפנה אליו מגיעה למצב סופי. מחיקה מוקדמת יותר עלולה להכשיל את המשימה.

## בדיקת תמיכת המודל

קובץ מאוחסן אינו שמיש אוטומטית עם כל מודל. המודל חייב להצהיר על מודאליות הקלט המתאימה בקטלוג הציבורי:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["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` של החלק.

| סוג | פורמטים | היכן אפשר להפנות אליו |
|---|---|---|
| PDF | PDF | Messages, Responses |
| תמונה | PNG, JPEG, GIF, WebP | Messages, Responses, יצירת תמונות, יצירת וידאו |
| וידאו | MP4 | יצירת וידאו |
| אודיו | MP3, WAV, FLAC, OGG | יצירת וידאו |
| Office | DOCX, XLSX, PPTX | אחסון בלבד |
| טקסט | טקסט UTF-8, נשמר כ-`text/plain` | אחסון בלבד |

כל תוכן אחר נדחה עם `invalid_file`.

### שמות קבצים

שם קובץ אינו יכול להכיל `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` או תווי בקרה. `/` מותר כמפריד, אך מקטעים ריקים, `.` ו-`..` אינם מותרים.

## ניהול קבצים

הקבצים שייכים לחשבון שלכם. כל מפתח API בחשבון רואה את אותם קבצים; חשבונות אחרים אינם יכולים להשתמש במזהי הקבצים שלכם.

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

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

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

### קבלת קובץ יחיד

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### מחיקת קובץ

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"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` | [אובייקט הקובץ](#section-17) |
| `GET` | `/api/v1/files` | [עמוד של קבצים](#section-19) |
| `GET` | `/api/v1/files/{file_id}` | [אובייקט הקובץ](#section-17) |
| `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:

```json
{
  "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`.

שגיאות אימות, יתרה ומגבלת קצב מתוארות ב[שגיאות, מגבלות וניסיונות חוזרים](https://openapi.felo.ai/he/docs/guides/errors-and-limits.md).

## קשור

- [פרוטוקולים ו-SDKs](https://openapi.felo.ai/he/docs/guides/protocols.md)
- [יצירת תמונות](https://openapi.felo.ai/he/docs/guides/image-generation.md)
- [משימות אסינכרוניות](https://openapi.felo.ai/he/docs/guides/async-tasks.md)
- [הפניה ל-Model API](https://openapi.felo.ai/he/docs/model-api)
