# رفع الملفات

ارفع الملف مرة واحدة، ثم أشر إليه بالمعرّف (ID) في طلبات Messages و Responses وتوليد الصور وتوليد الفيديو.

ارفع الملف مرة واحدة، ثم أشر إليه بمعرّفه في طلبات النماذج. يغنيك ذلك عن إعادة إرسال البايتات نفسها بصيغة base64 أو استضافة الملف على عنوان URL عام.

يعمل معرّف الملف مع Messages وResponses وتوليد الصور وتوليد الفيديو. ولا يعمل مع Chat Completions.

## قبل أن تبدأ

- مفتاح API. راجع [المصادقة](https://openapi.felo.ai/ar/docs/authentication.md).
- عنوان URL الأساسي `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.
- لا تُلحق معاملات استعلام بعنوان URL الخاص بالرفع.
- ارفع عبر HTTP بدلًا من مساعد Files في SDK. يرسل `files.create()` في OpenAI SDK الحقل `purpose` دائمًا، لذا لا يمكنه استدعاء هذا endpoint.
- الرفع الذي تنتهي مهلته أو ينقطع اتصاله ربما يكون قد خُزّن مع ذلك. اعرض قائمة ملفاتك قبل الرفع مجددًا.

## أين يمكن استخدام معرّف الملف

| 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

```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/ar/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` في استجابة الرفع إلى البيانات الوصفية للملف، لا إلى بايتاته. احتفظ بنسختك الخاصة من كل ما ترفعه.

لتنزيل الوسائط المولّدة، استخدم عناوين URL الموقّعة في `outputs` الخاصة بالمهمة.

## مرجع API

تستخدم جميع endpoints الرأس `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 | هل توجد صفحة أخرى |

## الأخطاء

تستخدم endpoints الملفات و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` في الأخطاء الصادرة عن endpoints الملفات. يعيد 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/ar/docs/guides/errors-and-limits.md).

## ذو صلة

- [البروتوكولات وSDKs](https://openapi.felo.ai/ar/docs/guides/protocols.md)
- [توليد الصور](https://openapi.felo.ai/ar/docs/guides/image-generation.md)
- [المهام غير المتزامنة](https://openapi.felo.ai/ar/docs/guides/async-tasks.md)
- [مرجع Model API](https://openapi.felo.ai/ar/docs/model-api)
