# ফাইল আপলোড

ফাইল একবার আপলোড করুন, তারপর Messages, Responses, ছবি তৈরি ও ভিডিও তৈরির অনুরোধে ID দিয়ে রেফারেন্স করুন।

একটি ফাইল একবার আপলোড করুন, তারপর মডেল অনুরোধে সেটিকে ID দিয়ে রেফারেন্স করুন। এটি একই বাইট base64 হিসেবে আবার পাঠানো বা ফাইলটি কোনো পাবলিক URL-এ হোস্ট করার বিকল্প।

ফাইল ID Messages, Responses, ইমেজ জেনারেশন ও ভিডিও জেনারেশনের সাথে কাজ করে। এটি Chat Completions-এর সাথে কাজ করে না।

## শুরু করার আগে

- একটি API key। [প্রমাণীকরণ](https://openapi.felo.ai/bn/docs/authentication.md) দেখুন।
- base URL `https://openapi.felo.ai`।
- এমন একটি মডেল যা আপনি যে ধরনের ফাইল পাঠাতে চান তা গ্রহণ করে। [মডেল সাপোর্ট যাচাই করুন](#section-6) দেখুন।

## দ্রুত শুরু

### 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` সংরক্ষণ করুন। এটিকে একটি opaque স্ট্রিং হিসেবে ধরুন: নিজে এটি তৈরি বা পার্স করবেন না।

### 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");
```

### আপলোডের নিয়ম

- 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

```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/bn/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"` দিয়ে দ্বিতীয় একটি এন্ট্রি যোগ করুন। শেষ ফ্রেমের জন্য প্রথম ফ্রেম আবশ্যক।

reference উপাদান `input_references`-এ যায়। প্রতিটি এন্ট্রি তার মিডিয়ার ধরনের সাথে মেলে এমন locator ব্যবহার করে:

```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` একই অনুরোধে ব্যবহার করা যায় না।

### Locator-এর নিয়ম

- ইমেজ ও ভিডিও অনুরোধে প্রতিটি `image_url`, `video_url` বা `audio_url` অবজেক্টে `file_id` বা `url`-এর মধ্যে ঠিক একটি থাকে, এবং অন্য কোনো ফিল্ড থাকে না।
- একটি অ্যারেতে `file_id` ব্যবহার করা এন্ট্রি ও `url` ব্যবহার করা এন্ট্রি একসাথে থাকতে পারে।
- ইমেজ ও ভিডিও জেনারেশন শুধু আপনার আপলোড করা ফাইল গ্রহণ করে। জেনারেট করা ইমেজ আবার ব্যবহার করতে তার output `url` পাঠান।
- ফাইল রেফারেন্স করা অনুরোধ ব্যর্থ হলে অন্য চ্যানেলে সরানো হয় না। ত্রুটি না দেখে এটিকে অন্য চ্যানেলে রিট্রাই করবেন না।
- একটি ফাইল রেফারেন্স করা প্রতিটি টাস্ক টার্মিনাল অবস্থায় না পৌঁছানো পর্যন্ত ফাইলটি রেখে দিন। আগে মুছে ফেললে টাস্ক ব্যর্থ হতে পারে।

## মডেল সাপোর্ট যাচাই করুন

সংরক্ষিত ফাইল স্বয়ংক্রিয়ভাবে সব মডেলের সাথে ব্যবহারযোগ্য হয় না। মডেলকে পাবলিক ক্যাটালগে সংশ্লিষ্ট input মোডালিটি ঘোষণা করতে হয়:

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

তালিকা খালি বা অনুপস্থিত থাকলে বুঝতে হবে ওই মডেলের জন্য ফাইল ID চালু নেই। তখন অনুরোধ `file_model_unsupported` দিয়ে ব্যর্থ হয়। মডেলের নাম দেখে সাপোর্ট অনুমান করবেন না।

## সীমা

| সীমা | মান |
|---|---|
| আপলোডের আকার | প্রতি ফাইলে 100 MiB (104,857,600 বাইট); খালি ফাইল প্রত্যাখ্যাত হয় |
| প্রতি মডেল অনুরোধে রেফারেন্স করা বাইট | মোট 50,000,000 বাইট |
| প্রতি মডেল অনুরোধে reference | 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 key একই ফাইল দেখে; অন্য অ্যাকাউন্ট আপনার ফাইল ID ব্যবহার করতে পারে না।

### ফাইলের তালিকা দেখুন

```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` header ফাইলের মেটাডেটার দিকে নির্দেশ করে, তার বাইটের দিকে নয়। আপনি যা-ই আপলোড করুন, তার নিজস্ব একটি কপি রাখুন।

জেনারেট করা মিডিয়া ডাউনলোড করতে টাস্কের `outputs`-এ থাকা স্বাক্ষরিত URL ব্যবহার করুন।

## API রেফারেন্স

সব endpoint `Authorization: Bearer YOUR_API_KEY` ব্যবহার করে। সফল রেসপন্স কোনো envelope ছাড়া সাধারণ JSON অবজেক্ট।

| মেথড | Path | যা ফেরত দেয় |
|---|---|---|
| `POST` | `/api/v1/files` | [ফাইল অবজেক্ট](#section-15) |
| `GET` | `/api/v1/files` | [ফাইলের একটি পেজ](#section-17) |
| `GET` | `/api/v1/files/{file_id}` | [ফাইল অবজেক্ট](#section-15) |
| `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 ব্যবহার করে:

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

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`-এ এই কোডগুলোর একটি থাকে।

প্রমাণীকরণ, ব্যালেন্স ও রেট সীমার ত্রুটি [ত্রুটি, সীমা ও রিট্রাই](https://openapi.felo.ai/bn/docs/guides/errors-and-limits.md)-এ বর্ণিত।

## সম্পর্কিত

- [প্রোটোকল এবং SDK সমূহ](https://openapi.felo.ai/bn/docs/guides/protocols.md)
- [ইমেজ জেনারেশন](https://openapi.felo.ai/bn/docs/guides/image-generation.md)
- [অ্যাসিঙ্ক টাস্ক](https://openapi.felo.ai/bn/docs/guides/async-tasks.md)
- [Model API reference](https://openapi.felo.ai/bn/docs/model-api)
