Felo API PlatformFelo API Platform

راهنماها

بارگذاری فایل

فایل را یک بار بارگذاری کنید و سپس در درخواست‌های Messages، Responses، تولید تصویر و تولید ویدیو با شناسه (ID) به آن ارجاع دهید.

فایل را یک بار بارگذاری کنید و سپس در درخواست‌های مدل با شناسه به آن ارجاع دهید. این کار جایگزین فرستادن دوباره همان بایت‌ها به‌صورت 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 بارگذاری پارامتر پرس‌وجو اضافه نکنید.
  • به‌جای ابزار کمکی Files یک SDK، از طریق HTTP بارگذاری کنید. 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

همه endpointها از 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اینکه صفحه دیگری وجود دارد یا نه

خطاها

endpointهای فایل، 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 برای خطاهای endpointهای فایل 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 پایان می‌یابد.

خطاهای احراز هویت، موجودی و محدودیت نرخ در خطاها، محدودیت‌ها و تلاش دوباره توضیح داده شده‌اند.

مرتبط

به کمک نیاز دارید؟

  • برای پرسش‌های مربوط به API، صورت‌حساب و حساب کاربری با پشتیبانی در تماس باشید.
  • با توسعه‌دهندگان Felo در Discord گفت‌وگو کنید.
  • تاریخچه تغییرات ما را ببینید.
  • به قیمت‌گذاری حجمی یا کمک در خرید نیاز دارید؟ تماس با فروش.
  • با LLM می‌سازید؟ llms.txt را بخوانید.