# فائل اپ لوڈ

فائل ایک بار اپ لوڈ کریں، پھر Messages، Responses، تصویر اور ویڈیو کی تیاری کی درخواستوں میں ID کے ذریعے اس کا حوالہ دیں۔

فائل ایک بار اپ لوڈ کریں، پھر ماڈل کی درخواستوں میں ID سے اُس کا حوالہ دیں۔ اِس سے وہی بائٹس base64 کی صورت میں دوبارہ بھیجنے یا فائل کو کسی عوامی URL پر ہوسٹ کرنے کی ضرورت نہیں رہتی۔

فائل ID Messages، Responses، تصویر جنریشن اور ویڈیو جنریشن کے ساتھ کام کرتی ہے۔ یہ Chat Completions کے ساتھ کام نہیں کرتی۔

## شروع کرنے سے پہلے

- ایک API کلید۔ [تصدیق](https://openapi.felo.ai/ur/docs/authentication.md) دیکھیں۔
- base URL `https://openapi.felo.ai`۔
- ایسا ماڈل جو وہ فائل ٹائپ قبول کرتا ہو جو آپ بھیجنا چاہتے ہیں۔ [ماڈل سپورٹ چیک کریں](#section-7) دیکھیں۔

## فوری آغاز

### 1. فائل اپ لوڈ کریں

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

کامیاب اپ لوڈ پر HTTP `200` کے ساتھ فائل کا میٹا ڈیٹا ملتا ہے:

```json
{
  "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. درخواست میں اِس کا حوالہ دیں

```bash
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 میں:

```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 یا اُس کے بعد کے ورژن میں:

```javascript
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

```json
{
  "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 ڈیٹا بھی نہیں ہونا چاہیے۔

### تصویر جنریشن

```json
{
  "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` جواب اور پولنگ [تصویر جنریشن](https://openapi.felo.ai/ur/docs/guides/image-generation.md) میں بیان کیے گئے ہیں۔

### ویڈیو جنریشن

پہلا اور آخری فریم `frame_images` میں جاتے ہیں:

```json
{
  "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` میں جاتا ہے۔ ہر اندراج وہ لوکیٹر استعمال کرتا ہے جو اُس کی میڈیا ٹائپ سے مطابقت رکھتا ہو:

```json
{
  "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` بھیجیں۔
- فائل کا حوالہ دینے والی درخواست ناکامی پر کسی دوسرے چینل پر منتقل نہیں کی جاتی۔ ایرر چیک کیے بغیر اِسے کسی مختلف چینل پر دوبارہ نہ آزمائیں۔
- فائل اُس وقت تک رکھیں جب تک اُس کا حوالہ دینے والا ہر ٹاسک آخری حالت تک نہ پہنچ جائے۔ اِسے پہلے حذف کرنے سے ٹاسک ناکام ہو سکتا ہے۔

## ماڈل سپورٹ چیک کریں

محفوظ شدہ فائل خود بخود ہر ماڈل کے ساتھ قابل استعمال نہیں ہوتی۔ ماڈل کے لیے لازم ہے کہ وہ عوامی کیٹلاگ میں متعلقہ اِن پٹ موڈیلٹی کا اعلان کرے:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| بھیجنے کے لیے | `input_modalities` میں یہ شامل ہونا لازمی ہے |
|---|---|
| PDF | `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` سے نہیں۔

| ٹائپ | فارمیٹس | کہاں حوالہ دیا جا سکتا ہے |
|---|---|---|
| PDF | PDF | 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 استعمال نہیں کر سکتے۔

### فائلوں کی فہرست

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "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` بھیجیں۔ سرور سائیڈ پر کوئی تلاش یا ٹائپ فلٹر نہیں ہے۔

### ایک فائل حاصل کریں

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### فائل حذف کریں

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"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` | [فائل آبجیکٹ](#section-16) |
| `GET` | `/api/v1/files` | [فائلوں کا ایک صفحہ](#section-18) |
| `GET` | `/api/v1/files/{file_id}` | [فائل آبجیکٹ](#section-16) |
| `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 ایرر انویلپ استعمال کرتے ہیں:

```json
{
  "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` میں اِن میں سے کوئی ایک کوڈ ہوتا ہے۔

تصدیق، بیلنس اور ریٹ کی حد کے ایررز [ایررز، حدود اور دوبارہ کوششیں](https://openapi.felo.ai/ur/docs/guides/errors-and-limits.md) میں بیان کیے گئے ہیں۔

## متعلقہ

- [پروٹوکول اور SDKز](https://openapi.felo.ai/ur/docs/guides/protocols.md)
- [تصویر جنریشن](https://openapi.felo.ai/ur/docs/guides/image-generation.md)
- [async ٹاسکس](https://openapi.felo.ai/ur/docs/guides/async-tasks.md)
- [Model API reference](https://openapi.felo.ai/ur/docs/model-api)
