رہنما
فائل اپ لوڈ
فائل ایک بار اپ لوڈ کریں، پھر Messages، Responses، تصویر اور ویڈیو کی تیاری کی درخواستوں میں ID کے ذریعے اس کا حوالہ دیں۔
فائل ایک بار اپ لوڈ کریں، پھر ماڈل کی درخواستوں میں ID سے اُس کا حوالہ دیں۔ اِس سے وہی بائٹس base64 کی صورت میں دوبارہ بھیجنے یا فائل کو کسی عوامی URL پر ہوسٹ کرنے کی ضرورت نہیں رہتی۔
فائل ID 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کے ساتھ مسترد ہو جاتا ہے۔ Content-Typeاپنے HTTP کلائنٹ کو سیٹ کرنے دیں۔ اِسے ہاتھ سے سیٹ کرنے پر multipart boundary غائب ہو جاتی ہے۔- اپ لوڈ URL کے ساتھ query parameters نہ لگائیں۔
- SDK کے Files ہیلپر کی بجائے HTTP کے ذریعے اپ لوڈ کریں۔ OpenAI SDK کا
files.create()ہمیشہpurposeبھیجتا ہے، لہٰذا وہ اِس endpoint کو کال نہیں کر سکتا۔ - جو اپ لوڈ ٹائم آؤٹ ہو جائے یا جس کا کنکشن ٹوٹ جائے، ممکن ہے وہ پھر بھی محفوظ ہو چکا ہو۔ دوبارہ اپ لوڈ کرنے سے پہلے اپنی فائلوں کی فہرست دیکھیں۔
فائل ID کہاں استعمال ہو سکتی ہے
| 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 میں یہ شامل ہونا لازمی ہے |
|---|---|
file | |
| تصویر | image |
| MP4 | video |
| آڈیو فائل | audio |
خالی یا غیر موجود فہرست کا مطلب ہے کہ اُس ماڈل کے لیے فائل IDs فعال نہیں ہیں۔ ایسی صورت میں درخواست 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 کلید وہی فائلیں دیکھتی ہے؛ دوسرے اکاؤنٹس آپ کی فائل IDs استعمال نہیں کر سکتے۔
فائلوں کی فہرست
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 ہیڈر فائل کے میٹا ڈیٹا کی طرف اشارہ کرتا ہے، اُس کے بائٹس کی طرف نہیں۔ جو کچھ بھی اپ لوڈ کریں اُس کی اپنی کاپی رکھیں۔
بنایا گیا میڈیا ڈاؤن لوڈ کرنے کے لیے ٹاسک کے outputs میں موجود دستخط شدہ URLs استعمال کریں۔
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 کسی بھی query parameter کو invalid_query کے ساتھ مسترد کرتے ہیں۔
فائل آبجیکٹ
| فیلڈ | ٹائپ | تفصیل |
|---|---|---|
id | string | فائل ID، جس کا سابقہ felo_file_ ہے۔ اِسے file_id کے طور پر استعمال کریں |
type | string | ہمیشہ file |
source | string | آپ کی اپ لوڈ کردہ فائلوں کے لیے upload، ماڈل آؤٹ پٹس کے لیے generated |
filename | string | اپ لوڈ کے ساتھ بھیجا گیا نام |
mime_type | string | مواد سے پہچانی گئی ٹائپ |
size_bytes | integer | سائز بائٹس میں |
created_at | string | ISO 8601 UTC ٹائم اسٹیمپ |
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 | صفحے کی پہلی فائل کی ID |
last_id | string یا null | صفحے کی آخری فائل کی ID |
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"
}
}فائلوں کے endpoints کے ایررز میں param null ہوتا ہے۔ Messages Anthropic کی ایرر ساخت واپس کرتا ہے، جس میں error.code نہیں ہوتا۔ request ID X-Request-Id response ہیڈر میں ہوتی ہے۔
فائلیں اپ لوڈ یا منظم کرتے وقت کے ایررز:
| 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 | غیر سپورٹ شدہ query parameter، یا 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 | غلط ساخت والی ID، ایک ہی لوکیٹر میں 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 کو فائل ID بھیجی گئی |
| 404 | file_not_found | فائل موجود نہیں، حذف ہو چکی ہے، کسی دوسرے اکاؤنٹ کی ملکیت ہے، یا ایسی بنائی گئی فائل ہے جو تصویر یا ویڈیو جنریشن کو بھیجی گئی |
تصویر اور ویڈیو جنریشن میں فائل 202 کے بعد بھی ناکام ہو سکتی ہے۔ ایسی صورت میں ٹاسک failed پر ختم ہوتا ہے اور error.code میں اِن میں سے کوئی ایک کوڈ ہوتا ہے۔
تصدیق، بیلنس اور ریٹ کی حد کے ایررز ایررز، حدود اور دوبارہ کوششیں میں بیان کیے گئے ہیں۔
متعلقہ
مدد چاہیے؟
- API، بلنگ اور اکاؤنٹ سے متعلق سوالات کے لیے سپورٹ سے رابطہ کریں۔
- Discord پر Felo ڈویلپرز سے بات کریں۔
- ہماری تازہ تبدیلیاں دیکھیں۔
- حجم کے حساب سے قیمت یا خریداری میں مدد چاہیے؟ سیلز ٹیم سے رابطہ کریں۔
- LLM کے ساتھ بنا رہے ہیں؟ llms.txt پڑھیں۔