# फ़ाइल अपलोड

फ़ाइल एक बार अपलोड करें, फिर Messages, Responses, इमेज जनरेशन और वीडियो जनरेशन रिक्वेस्ट में ID से उसका संदर्भ दें।

फ़ाइल एक बार अपलोड करें, फिर मॉडल अनुरोधों में उसे ID से संदर्भित करें। यह वही बाइट दोबारा base64 के रूप में भेजने या फ़ाइल को किसी सार्वजनिक URL पर होस्ट करने की जगह लेता है।

फ़ाइल ID Messages, Responses, इमेज जनरेशन और वीडियो जनरेशन के साथ काम करता है। यह Chat Completions के साथ काम नहीं करता।

## शुरू करने से पहले

- एक API key। [प्रमाणीकरण](https://openapi.felo.ai/hi/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` सहेज लें। इसे अपारदर्शी string मानें: इसे न खुद बनाएं, न पार्स करें।

### 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` के साथ अस्वीकार कर दिया जाता है।
- `Content-Type` अपने HTTP क्लाइंट को सेट करने दें। इसे हाथ से सेट करने पर multipart boundary छूट जाती है।
- अपलोड URL में query पैरामीटर न जोड़ें।
- SDK के Files helper के बजाय 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/hi/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` में जाती है। हर प्रविष्टि अपने मीडिया प्रकार से मेल खाने वाला 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` में से ठीक एक होता है, और कोई अन्य फ़ील्ड नहीं।
- एक ही array में `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` |

खाली या गुम सूची का अर्थ है कि उस मॉडल के लिए फ़ाइल ID सक्षम नहीं हैं। तब अनुरोध `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 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` हेडर फ़ाइल के मेटाडेटा की ओर इशारा करता है, उसके बाइट की ओर नहीं। जो कुछ भी आप अपलोड करें, उसकी अपनी प्रति रखें।

जनरेट किया गया मीडिया डाउनलोड करने के लिए कार्य के `outputs` में दिए साइन किए गए URL का उपयोग करें।

## API संदर्भ

सभी endpoint `Authorization: Bearer YOUR_API_KEY` का उपयोग करते हैं। सफल प्रतिक्रियाएं बिना envelope के सादे JSON ऑब्जेक्ट होती हैं।

| मेथड | पथ | क्या लौटाता है |
|---|---|---|
| `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`, मॉडल आउटपुट के लिए `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 | क्या कोई और पेज मौजूद है |

## त्रुटियां

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` प्रतिक्रिया हेडर में होता है।

फ़ाइलें अपलोड या प्रबंधित करते समय की त्रुटियां:

| 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 से अधिक संदर्भ हैं |
| 400 | `unsupported_file_type` | फ़ाइल का प्रकार उसकी जगह से मेल नहीं खाता, उदाहरण के लिए दस्तावेज़ ब्लॉक में MP4 |
| 400 | `file_model_unsupported` | मॉडल आवश्यक इनपुट मोडैलिटी घोषित नहीं करता |
| 400 | `file_input_too_large` | संदर्भित फ़ाइलें कुल 50,000,000 बाइट से अधिक हैं |
| 400 | `file_protocol_unsupported` | फ़ाइल ID Chat Completions को भेजा गया |
| 404 | `file_not_found` | फ़ाइल गुम है, हटा दी गई है, किसी अन्य खाते की है, या इमेज या वीडियो जनरेशन को भेजी गई जनरेट की हुई फ़ाइल है |

इमेज और वीडियो जनरेशन में फ़ाइल `202` के बाद भी विफल हो सकती है। तब कार्य `failed` के रूप में समाप्त होता है और `error.code` में इनमें से कोई एक कोड होता है।

प्रमाणीकरण, बैलेंस और दर सीमा की त्रुटियां [त्रुटियां, सीमाएं और पुनः प्रयास](https://openapi.felo.ai/hi/docs/guides/errors-and-limits.md) में बताई गई हैं।

## संबंधित

- [प्रोटोकॉल और SDK](https://openapi.felo.ai/hi/docs/guides/protocols.md)
- [इमेज जनरेशन](https://openapi.felo.ai/hi/docs/guides/image-generation.md)
- [असिंक्रोनस कार्य](https://openapi.felo.ai/hi/docs/guides/async-tasks.md)
- [Model API reference](https://openapi.felo.ai/hi/docs/model-api)
