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.
  • لا تُلحق معاملات استعلام بعنوان URL الخاص بالرفع.
  • ارفع عبر HTTP بدلًا من مساعد Files في SDK. يرسل files.create() في OpenAI SDK الحقل purpose دائمًا، لذا لا يمكنه استدعاء هذا endpoint.
  • الرفع الذي تنتهي مهلته أو ينقطع اتصاله ربما يكون قد خُزّن مع ذلك. اعرض قائمة ملفاتك قبل الرفع مجددًا.

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

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

لتنزيل الوسائط المولّدة، استخدم عناوين 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}/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هل توجد صفحة أخرى

الأخطاء

تستخدم 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.

الأخطاء عند رفع الملفات أو إدارتها:

HTTPerror.codeالمعنى
400invalid_content_typeجسم الطلب ليس multipart/form-data
400invalid_fileلا يوجد جزء file، أو يوجد جزء إضافي، أو الملف فارغ، أو المحتوى غير مدعوم
400invalid_filenameاسم الملف طويل جدًا أو يحتوي على حرف مرفوض
413file_too_largeيتجاوز الملف 100 MiB
400invalid_queryمعامل استعلام غير مدعوم، أو قيمة order غير asc
400invalid_limitقيمة limit خارج النطاق من 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.

أخطاء المصادقة والرصيد وحدود المعدل موصوفة في الأخطاء والحدود وإعادة المحاولة.

ذو صلة

هل تحتاج إلى مساعدة؟