الأدلة
رفع الملفات
ارفع الملف مرة واحدة، ثم أشر إليه بالمعرّف (ID) في طلبات Messages و Responses وتوليد الصور وتوليد الفيديو.
ارفع الملف مرة واحدة، ثم أشر إليه بمعرّفه في طلبات النماذج. يغنيك ذلك عن إعادة إرسال البايتات نفسها بصيغة base64 أو استضافة الملف على عنوان URL عام.
يعمل معرّف الملف مع Messages وResponses وتوليد الصور وتوليد الفيديو. ولا يعمل مع Chat Completions.
قبل أن تبدأ
- مفتاح API. راجع المصادقة.
- عنوان URL الأساسي
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. - لا تُلحق معاملات استعلام بعنوان 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
{
"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 في استجابة الرفع إلى البيانات الوصفية للملف، لا إلى بايتاته. احتفظ بنسختك الخاصة من كل ما ترفعه.
لتنزيل الوسائط المولّدة، استخدم عناوين URL الموقّعة في outputs الخاصة بالمهمة.
مرجع API
تستخدم جميع endpoints الرأس 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 | هل توجد صفحة أخرى |
الأخطاء
تستخدم endpoints الملفات و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 في الأخطاء الصادرة عن 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.
أخطاء المصادقة والرصيد وحدود المعدل موصوفة في الأخطاء والحدود وإعادة المحاولة.
ذو صلة
هل تحتاج إلى مساعدة؟
- للأسئلة حول API والفوترة والحساب، تواصل مع الدعم.
- تحدّث مع مطوّري Felo على Discord.
- اطّلع على سجل التغييرات.
- تحتاج إلى تسعير حسب الحجم أو مساعدة في الشراء؟ تواصل مع فريق المبيعات.
- تبني باستخدام LLM؟ اقرأ llms.txt.