গাইড
ফাইল আপলোড
ফাইল একবার আপলোড করুন, তারপর Messages, Responses, ছবি তৈরি ও ভিডিও তৈরির অনুরোধে ID দিয়ে রেফারেন্স করুন।
একটি ফাইল একবার আপলোড করুন, তারপর মডেল অনুরোধে সেটিকে ID দিয়ে রেফারেন্স করুন। এটি একই বাইট base64 হিসেবে আবার পাঠানো বা ফাইলটি কোনো পাবলিক URL-এ হোস্ট করার বিকল্প।
ফাইল ID Messages, Responses, ইমেজ জেনারেশন ও ভিডিও জেনারেশনের সাথে কাজ করে। এটি Chat Completions-এর সাথে কাজ করে না।
শুরু করার আগে
- একটি API key। প্রমাণীকরণ দেখুন।
- 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 সংরক্ষণ করুন। এটিকে একটি opaque স্ট্রিং হিসেবে ধরুন: নিজে এটি তৈরি বা পার্স করবেন না।
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");আপলোডের নিয়ম
- body হলো
multipart/form-data, যাতে ঠিক একটি পার্ট থাকে, যার নামfile।purposeসহ অন্য যেকোনো পার্টinvalid_fileদিয়ে প্রত্যাখ্যাত হয়। - আপনার HTTP ক্লায়েন্টকে
Content-Typeসেট করতে দিন। হাতে সেট করলে multipart boundary বাদ পড়ে যায়। - আপলোড URL-এ query প্যারামিটার যোগ করবেন না।
- SDK-র Files helper-এর বদলে HTTP দিয়ে আপলোড করুন। OpenAI SDK-র
files.create()সবসময়purposeপাঠায়, তাই এটি এই endpoint কল করতে পারে না। - যে আপলোড টাইমআউট হয় বা যার সংযোগ বিচ্ছিন্ন হয়, সেটি তবুও সংরক্ষিত হয়ে থাকতে পারে। আবার আপলোড করার আগে আপনার ফাইলগুলোর তালিকা দেখুন।
ফাইল ID কোথায় ব্যবহার করা যায়
| Endpoint | ফাইলের ধরন | প্রয়োজনীয় input মোডালিটি | ফিল্ড |
|---|---|---|---|
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" দিয়ে দ্বিতীয় একটি এন্ট্রি যোগ করুন। শেষ ফ্রেমের জন্য প্রথম ফ্রেম আবশ্যক।
reference উপাদান input_references-এ যায়। প্রতিটি এন্ট্রি তার মিডিয়ার ধরনের সাথে মেলে এমন locator ব্যবহার করে:
{
"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 একই অনুরোধে ব্যবহার করা যায় না।
Locator-এর নিয়ম
- ইমেজ ও ভিডিও অনুরোধে প্রতিটি
image_url,video_urlবাaudio_urlঅবজেক্টেfile_idবাurl-এর মধ্যে ঠিক একটি থাকে, এবং অন্য কোনো ফিল্ড থাকে না। - একটি অ্যারেতে
file_idব্যবহার করা এন্ট্রি ওurlব্যবহার করা এন্ট্রি একসাথে থাকতে পারে। - ইমেজ ও ভিডিও জেনারেশন শুধু আপনার আপলোড করা ফাইল গ্রহণ করে। জেনারেট করা ইমেজ আবার ব্যবহার করতে তার output
urlপাঠান। - ফাইল রেফারেন্স করা অনুরোধ ব্যর্থ হলে অন্য চ্যানেলে সরানো হয় না। ত্রুটি না দেখে এটিকে অন্য চ্যানেলে রিট্রাই করবেন না।
- একটি ফাইল রেফারেন্স করা প্রতিটি টাস্ক টার্মিনাল অবস্থায় না পৌঁছানো পর্যন্ত ফাইলটি রেখে দিন। আগে মুছে ফেললে টাস্ক ব্যর্থ হতে পারে।
মডেল সাপোর্ট যাচাই করুন
সংরক্ষিত ফাইল স্বয়ংক্রিয়ভাবে সব মডেলের সাথে ব্যবহারযোগ্য হয় না। মডেলকে পাবলিক ক্যাটালগে সংশ্লিষ্ট input মোডালিটি ঘোষণা করতে হয়:
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-এ যা থাকতে হবে |
|---|---|
file | |
| ইমেজ | image |
| MP4 | video |
| অডিও ফাইল | audio |
তালিকা খালি বা অনুপস্থিত থাকলে বুঝতে হবে ওই মডেলের জন্য ফাইল ID চালু নেই। তখন অনুরোধ file_model_unsupported দিয়ে ব্যর্থ হয়। মডেলের নাম দেখে সাপোর্ট অনুমান করবেন না।
সীমা
| সীমা | মান |
|---|---|
| আপলোডের আকার | প্রতি ফাইলে 100 MiB (104,857,600 বাইট); খালি ফাইল প্রত্যাখ্যাত হয় |
| প্রতি মডেল অনুরোধে রেফারেন্স করা বাইট | মোট 50,000,000 বাইট |
| প্রতি মডেল অনুরোধে reference | 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 key একই ফাইল দেখে; অন্য অ্যাকাউন্ট আপনার ফাইল ID ব্যবহার করতে পারে না।
ফাইলের তালিকা দেখুন
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 header ফাইলের মেটাডেটার দিকে নির্দেশ করে, তার বাইটের দিকে নয়। আপনি যা-ই আপলোড করুন, তার নিজস্ব একটি কপি রাখুন।
জেনারেট করা মিডিয়া ডাউনলোড করতে টাস্কের outputs-এ থাকা স্বাক্ষরিত URL ব্যবহার করুন।
API রেফারেন্স
সব endpoint Authorization: Bearer YOUR_API_KEY ব্যবহার করে। সফল রেসপন্স কোনো envelope ছাড়া সাধারণ JSON অবজেক্ট।
| মেথড | Path | যা ফেরত দেয় |
|---|---|---|
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 যেকোনো query প্যারামিটার invalid_query দিয়ে প্রত্যাখ্যান করে।
ফাইল অবজেক্ট
| ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
id | string | ফাইল ID, যার প্রিফিক্স felo_file_। এটি file_id হিসেবে ব্যবহার করুন |
type | string | সবসময় file |
source | string | আপনার আপলোড করা ফাইলের জন্য upload, মডেল output-এর জন্য generated |
filename | string | আপলোডের সাথে পাঠানো নাম |
mime_type | string | কনটেন্ট থেকে শনাক্ত করা ধরন |
size_bytes | integer | বাইটে আকার |
created_at | string | ISO 8601 UTC টাইমস্ট্যাম্প |
downloadable | boolean | আপলোড করা ফাইলের জন্য false |
আপলোড অনুরোধ
| পার্ট | আবশ্যক | বর্ণনা |
|---|---|---|
file | হ্যাঁ | ফাইলটি, যা ফাইলনামসহ একটি multipart/form-data ফাইল পার্ট হিসেবে পাঠানো হয় |
রেসপন্সে একটি Location header থাকে, যাতে ফাইলের মেটাডেটার URL থাকে।
তালিকার প্যারামিটার
| প্যারামিটার | ডিফল্ট | বর্ণনা |
|---|---|---|
limit | 100 | পেজের আকার, 1 থেকে 1000 |
cursor | আগের পেজ থেকে পাওয়া cursor মান | |
after, after_id | cursor-এর বিকল্প নাম। তিনটির মধ্যে শুধু একটি পাঠান | |
order | asc | শুধু asc সমর্থিত |
| রেসপন্স ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
data | array | ফাইল অবজেক্ট, সবচেয়ে পুরোনো আগে |
first_id | string বা null | পেজের প্রথম ফাইলের ID |
last_id | string বা null | পেজের শেষ ফাইলের ID |
cursor | string বা null | পরের পেজের জন্য cursor হিসেবে পাঠানোর মান |
has_more | boolean | আরেকটি পেজ আছে কি না |
ত্রুটি
Files endpoint, Responses এবং ইমেজ ও ভিডিও জেনারেশন OpenAI error envelope ব্যবহার করে:
{
"error": {
"message": "This model does not accept this attachment type",
"type": "invalid_request_error",
"param": "frame_images.0.image_url",
"code": "file_model_unsupported"
}
}Files endpoint-এর ত্রুটির ক্ষেত্রে param হলো null। Messages Anthropic-এর error shape ফেরত দেয়, যাতে error.code নেই। request ID X-Request-Id রেসপন্স header-এ থাকে।
ফাইল আপলোড বা পরিচালনার সময়ের ত্রুটি:
| HTTP | error.code | অর্থ |
|---|---|---|
| 400 | invalid_content_type | body multipart/form-data নয় |
| 400 | invalid_file | file পার্ট নেই, অতিরিক্ত পার্ট আছে, ফাইল খালি, বা কনটেন্ট সমর্থিত নয় |
| 400 | invalid_filename | ফাইলনাম খুব লম্বা বা তাতে প্রত্যাখ্যাত অক্ষর আছে |
| 413 | file_too_large | ফাইল 100 MiB ছাড়িয়েছে |
| 400 | invalid_query | অসমর্থিত query প্যারামিটার, বা order-এর মান asc ছাড়া অন্য কিছু |
| 400 | invalid_limit | limit 1 থেকে 1000-এর বাইরে |
| 400 | invalid_cursor | cursor-এর ফরম্যাট ভুল, বা একাধিক 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 | ID-র ফরম্যাট ভুল, একটি locator-এ file_id ও url দুটোই আছে, বা 100টির বেশি reference |
| 400 | unsupported_file_type | ফাইলের ধরন অবস্থানের সাথে মেলে না, যেমন ডকুমেন্ট ব্লকে MP4 |
| 400 | file_model_unsupported | মডেল প্রয়োজনীয় input মোডালিটি ঘোষণা করে না |
| 400 | file_input_too_large | রেফারেন্স করা ফাইলগুলো মোট 50,000,000 বাইট ছাড়িয়েছে |
| 400 | file_protocol_unsupported | Chat Completions-এ একটি ফাইল ID পাঠানো হয়েছে |
| 404 | file_not_found | ফাইলটি নেই, মুছে ফেলা হয়েছে, অন্য অ্যাকাউন্টের, বা এটি ইমেজ বা ভিডিও জেনারেশনে পাঠানো একটি জেনারেট করা ফাইল |
ইমেজ ও ভিডিও জেনারেশনে ফাইল 202-এর পরেও ব্যর্থ হতে পারে। তখন টাস্ক failed হিসেবে শেষ হয় এবং error.code-এ এই কোডগুলোর একটি থাকে।
প্রমাণীকরণ, ব্যালেন্স ও রেট সীমার ত্রুটি ত্রুটি, সীমা ও রিট্রাই-এ বর্ণিত।
সম্পর্কিত
সাহায্য দরকার?
- API, বিলিং ও অ্যাকাউন্ট সংক্রান্ত প্রশ্নে সাপোর্ট-এর সাথে যোগাযোগ করুন।
- Discord-এ Felo ডেভেলপারদের সাথে কথা বলুন।
- আমাদের পরিবর্তনের তালিকা দেখুন।
- বাল্ক দাম বা কেনাকাটায় সাহায্য দরকার? সেলস টিমের সাথে যোগাযোগ করুন।
- LLM দিয়ে তৈরি করছেন? llms.txt পড়ুন।