# การอัปโหลดไฟล์

อัปโหลดไฟล์ครั้งเดียว แล้วอ้างอิงด้วย ID ในคำขอ Messages, Responses, การสร้างภาพ และการสร้างวิดีโอ

อัปโหลดไฟล์ครั้งเดียว แล้วอ้างอิงด้วย ID ในคำขอไปยังโมเดล วิธีนี้ใช้แทนการส่งไบต์ชุดเดิมซ้ำเป็น base64 หรือการโฮสต์ไฟล์ไว้ที่ URL สาธารณะ

ID ไฟล์ใช้ได้กับ Messages, Responses, การสร้างรูปภาพ และการสร้างวิดีโอ แต่ใช้กับ Chat Completions ไม่ได้

## ก่อนเริ่มต้น

- คีย์ API ดู[การรับรองความถูกต้อง](https://openapi.felo.ai/th/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` ไว้ ให้ถือว่าเป็นสตริงแบบ 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");
```

### กฎการอัปโหลด

- เนื้อหาคำขอเป็น `multipart/form-data` ที่มีเพียงส่วนเดียวชื่อ `file` ส่วนอื่นใด รวมถึง `purpose` จะถูกปฏิเสธด้วย `invalid_file`
- ให้ไคลเอนต์ HTTP ตั้งค่า `Content-Type` เอง การตั้งค่าด้วยมือจะทำให้ multipart boundary หายไป
- อย่าเพิ่มพารามิเตอร์คิวรีต่อท้าย URL อัปโหลด
- อัปโหลดผ่าน HTTP แทนการใช้ตัวช่วย Files ของ SDK เพราะ `files.create()` ของ OpenAI SDK ส่ง `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/th/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` |

รายการที่ว่างเปล่าหรือไม่มีอยู่หมายความว่ายังไม่ได้เปิดใช้ 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 ทุกคีย์ในบัญชีเห็นไฟล์ชุดเดียวกัน บัญชีอื่นใช้ 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` และ header `Location` ของการตอบกลับการอัปโหลดชี้ไปยังเมทาดาทาของไฟล์ ไม่ใช่ไบต์ของไฟล์ ให้เก็บสำเนาของทุกอย่างที่คุณอัปโหลดไว้เอง

หากต้องการดาวน์โหลดสื่อที่สร้างขึ้น ให้ใช้ URL ที่ลงนามใน `outputs` ของงาน

## เอกสารอ้างอิง API

endpoint ทั้งหมดใช้ `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` แบบไฟล์เดียวปฏิเสธพารามิเตอร์คิวรีทุกตัวด้วย `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 | ไทม์สแตมป์ UTC แบบ ISO 8601 |
| `downloadable` | boolean | `false` สำหรับไฟล์ที่อัปโหลด |

### คำขออัปโหลด

| ส่วน | จำเป็น | คำอธิบาย |
|---|---|---|
| `file` | ใช่ | ตัวไฟล์ ส่งเป็นส่วนไฟล์ของ `multipart/form-data` พร้อมชื่อไฟล์ |

การตอบกลับมี header `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 | มีหน้าถัดไปหรือไม่ |

## ข้อผิดพลาด

endpoint ของ Files, 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` เป็น `null` สำหรับข้อผิดพลาดจาก endpoint ของ Files ส่วน Messages ส่งรูปแบบข้อผิดพลาดของ Anthropic ซึ่งไม่มี `error.code` request ID อยู่ใน header การตอบกลับ `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` | 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` | ส่ง ID ไฟล์ไปยัง Chat Completions |
| 404 | `file_not_found` | ไฟล์ไม่มีอยู่ ถูกลบแล้ว เป็นของบัญชีอื่น หรือเป็นไฟล์ที่สร้างขึ้นซึ่งถูกส่งไปยังการสร้างรูปภาพหรือวิดีโอ |

สำหรับการสร้างรูปภาพและวิดีโอ ไฟล์อาจล้มเหลวหลัง `202` ได้เช่นกัน งานจะสิ้นสุดเป็น `failed` โดยมีรหัสข้างต้นรหัสใดรหัสหนึ่งใน `error.code`

ข้อผิดพลาดด้านการรับรองความถูกต้อง ยอดคงเหลือ และขีดจำกัดอัตราอธิบายไว้ใน[ข้อผิดพลาด ขีดจำกัด และการลองใหม่](https://openapi.felo.ai/th/docs/guides/errors-and-limits.md)

## เนื้อหาที่เกี่ยวข้อง

- [โปรโตคอลและ SDKs](https://openapi.felo.ai/th/docs/guides/protocols.md)
- [การสร้างรูปภาพ](https://openapi.felo.ai/th/docs/guides/image-generation.md)
- [งานอะซิงโครนัส](https://openapi.felo.ai/th/docs/guides/async-tasks.md)
- [Model API reference](https://openapi.felo.ai/th/docs/model-api)
