راهنماها
بارگذاری فایل
فایل را یک بار بارگذاری کنید و سپس در درخواستهای Messages، Responses، تولید تصویر و تولید ویدیو با شناسه (ID) به آن ارجاع دهید.
فایل را یک بار بارگذاری کنید و سپس در درخواستهای مدل با شناسه به آن ارجاع دهید. این کار جایگزین فرستادن دوباره همان بایتها بهصورت base64 یا میزبانی فایل روی یک URL عمومی میشود.
شناسه فایل با Messages، Responses، تولید تصویر و تولید ویدیو کار میکند. با Chat Completions کار نمیکند.
پیش از شروع
- یک کلید API. احراز هویت را ببینید.
- base 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 بارگذاری پارامتر پرسوجو اضافه نکنید.
- بهجای ابزار کمکی Files یک SDK، از طریق HTTP بارگذاری کنید.
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
همه 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}/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 | اینکه صفحه دیگری وجود دارد یا نه |
خطاها
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 است.
خطاهای هنگام بارگذاری یا مدیریت فایلها:
| 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 را بخوانید.