# بارگذاری فایل

فایل را یک بار بارگذاری کنید و سپس در درخواست‌های Messages، Responses، تولید تصویر و تولید ویدیو با شناسه (ID) به آن ارجاع دهید.

فایل را یک بار بارگذاری کنید و سپس در درخواست‌های مدل با شناسه به آن ارجاع دهید. این کار جایگزین فرستادن دوباره همان بایت‌ها به‌صورت base64 یا میزبانی فایل روی یک URL عمومی می‌شود.

شناسه فایل با Messages، Responses، تولید تصویر و تولید ویدیو کار می‌کند. با Chat Completions کار نمی‌کند.

## پیش از شروع

- یک کلید API. [احراز هویت](https://openapi.felo.ai/fa/docs/authentication.md) را ببینید.
- base URL برابر `https://openapi.felo.ai`.
- مدلی که نوع فایل موردنظر شما را می‌پذیرد. [بررسی پشتیبانی مدل](#section-8) را ببینید.

## شروع سریع

### 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` رد می‌شود.
- بگذارید کلاینت 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

```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/fa/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` |

فهرست خالی یا ناموجود یعنی شناسه فایل برای آن مدل فعال نیست. در این صورت درخواست با `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 حساب همان فایل‌ها را می‌بینند؛ حساب‌های دیگر نمی‌توانند از شناسه فایل‌های شما استفاده کنند.

### فهرست فایل‌ها

```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` در پاسخ بارگذاری به فراداده فایل اشاره می‌کند، نه بایت‌های آن. از هر چیزی که بارگذاری می‌کنید نسخه‌ای نزد خودتان نگه دارید.

برای دانلود رسانه تولیدشده، از URLهای امضاشده در `outputs` وظیفه استفاده کنید.

## مرجع API

همه endpointها از `Authorization: Bearer YOUR_API_KEY` استفاده می‌کنند. پاسخ‌های موفق اشیای JSON ساده و بدون پوشش‌اند.

| متد | مسیر | برمی‌گرداند |
|---|---|---|
| `POST` | `/api/v1/files` | [شیء فایل](#section-17) |
| `GET` | `/api/v1/files` | [صفحه‌ای از فایل‌ها](#section-19) |
| `GET` | `/api/v1/files/{file_id}` | [شیء فایل](#section-17) |
| `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 استفاده می‌کنند:

```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"
  }
}
```

`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` پایان می‌یابد.

خطاهای احراز هویت، موجودی و محدودیت نرخ در [خطاها، محدودیت‌ها و تلاش دوباره](https://openapi.felo.ai/fa/docs/guides/errors-and-limits.md) توضیح داده شده‌اند.

## مرتبط

- [پروتکل‌ها و SDKها](https://openapi.felo.ai/fa/docs/guides/protocols.md)
- [تولید تصویر](https://openapi.felo.ai/fa/docs/guides/image-generation.md)
- [وظایف ناهمگام](https://openapi.felo.ai/fa/docs/guides/async-tasks.md)
- [مرجع Model API](https://openapi.felo.ai/fa/docs/model-api)
