Felo API PlatformFelo API Platform

رہنما

فائل اپ لوڈ

فائل ایک بار اپ لوڈ کریں، پھر 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/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

خالی یا غیر موجود فہرست کا مطلب ہے کہ اُس ماڈل کے لیے فائل IDs فعال نہیں ہیں۔ ایسی صورت میں درخواست 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 کلید وہی فائلیں دیکھتی ہے؛ دوسرے اکاؤنٹس آپ کی فائل 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}/content400 file_not_downloadable

POST، DELETE اور واحد فائل والا GET کسی بھی query parameter کو invalid_query کے ساتھ مسترد کرتے ہیں۔

فائل آبجیکٹ

فیلڈٹائپتفصیل
idstringفائل ID، جس کا سابقہ felo_file_ ہے۔ اِسے file_id کے طور پر استعمال کریں
typestringہمیشہ file
sourcestringآپ کی اپ لوڈ کردہ فائلوں کے لیے upload، ماڈل آؤٹ پٹس کے لیے generated
filenamestringاپ لوڈ کے ساتھ بھیجا گیا نام
mime_typestringمواد سے پہچانی گئی ٹائپ
size_bytesintegerسائز بائٹس میں
created_atstringISO 8601 UTC ٹائم اسٹیمپ
downloadablebooleanاپ لوڈ کی گئی فائلوں کے لیے false

اپ لوڈ کی درخواست

حصہلازمیتفصیل
fileہاںفائل، جو multipart/form-data کے فائل حصے کے طور پر فائل نام کے ساتھ بھیجی جاتی ہے

جواب میں Location ہیڈر شامل ہوتا ہے جس میں فائل کے میٹا ڈیٹا کا URL ہوتا ہے۔

فہرست کے پیرامیٹرز

پیرامیٹرڈیفالٹتفصیل
limit100صفحے کا سائز، 1 سے 1000 تک
cursorپچھلے صفحے کی cursor ویلیو
after، after_idcursor کے متبادل نام۔ تینوں میں سے صرف ایک بھیجیں
orderascصرف asc سپورٹ ہوتا ہے
جواب کا فیلڈٹائپتفصیل
dataarrayفائل آبجیکٹس، پرانے سے نئے کی ترتیب میں
first_idstring یا nullصفحے کی پہلی فائل کی ID
last_idstring یا nullصفحے کی آخری فائل کی ID
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"
  }
}

فائلوں کے endpoints کے ایررز میں param null ہوتا ہے۔ Messages Anthropic کی ایرر ساخت واپس کرتا ہے، جس میں error.code نہیں ہوتا۔ request ID X-Request-Id response ہیڈر میں ہوتی ہے۔

فائلیں اپ لوڈ یا منظم کرتے وقت کے ایررز:

HTTPerror.codeمطلب
400invalid_content_typeباڈی multipart/form-data نہیں ہے
400invalid_filefile حصہ موجود نہیں، کوئی اضافی حصہ ہے، فائل خالی ہے، یا مواد سپورٹ نہیں ہوتا
400invalid_filenameفائل کا نام بہت لمبا ہے یا اُس میں کوئی ممنوعہ حرف ہے
413file_too_largeفائل 100 MiB سے بڑی ہے
400invalid_queryغیر سپورٹ شدہ query parameter، یا 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غلط ساخت والی ID، ایک ہی لوکیٹر میں file_id اور url دونوں، یا 100 سے زیادہ ریفرنسز
400unsupported_file_typeفائل کی ٹائپ جگہ سے مطابقت نہیں رکھتی، مثلاً دستاویز بلاک میں MP4
400file_model_unsupportedماڈل مطلوبہ اِن پٹ موڈیلٹی کا اعلان نہیں کرتا
400file_input_too_largeحوالہ شدہ فائلیں مجموعی طور پر 50,000,000 بائٹس سے زیادہ ہیں
400file_protocol_unsupportedChat Completions کو فائل ID بھیجی گئی
404file_not_foundفائل موجود نہیں، حذف ہو چکی ہے، کسی دوسرے اکاؤنٹ کی ملکیت ہے، یا ایسی بنائی گئی فائل ہے جو تصویر یا ویڈیو جنریشن کو بھیجی گئی

تصویر اور ویڈیو جنریشن میں فائل 202 کے بعد بھی ناکام ہو سکتی ہے۔ ایسی صورت میں ٹاسک failed پر ختم ہوتا ہے اور error.code میں اِن میں سے کوئی ایک کوڈ ہوتا ہے۔

تصدیق، بیلنس اور ریٹ کی حد کے ایررز ایررز، حدود اور دوبارہ کوششیں میں بیان کیے گئے ہیں۔

متعلقہ

مدد چاہیے؟