# Tải tệp lên

Tải tệp lên một lần, sau đó tham chiếu bằng ID trong các yêu cầu Messages, Responses, tạo hình ảnh và tạo video.

Tải tệp lên một lần, sau đó tham chiếu tệp bằng ID trong các yêu cầu gửi đến mô hình. Cách này thay cho việc gửi lại cùng các byte đó dưới dạng base64 hoặc lưu trữ tệp tại một URL công khai.

ID tệp dùng được với Messages, Responses, tạo hình ảnh và tạo video. ID tệp không dùng được với Chat Completions.

## Trước khi bắt đầu

- Một khóa API. Xem [Xác thực](https://openapi.felo.ai/vi/docs/authentication.md).
- Base URL `https://openapi.felo.ai`.
- Một mô hình chấp nhận loại tệp bạn định gửi. Xem [Kiểm tra khả năng hỗ trợ của mô hình](#ki-m-tra-kh-n-ng-h-tr-c-a-m-h-nh).

## Bắt đầu nhanh

### 1. Tải tệp lên

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

Tải lên thành công trả về HTTP `200` kèm siêu dữ liệu của tệp:

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

Lưu lại `id`. Hãy coi nó là một chuỗi opaque: đừng tự tạo hay phân tích nó.

### 2. Tham chiếu tệp trong yêu cầu

```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."}
        ]
      }
    ]
  }'
```

Hai bước tương tự bằng 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())
```

Và bằng Node.js 20 trở lên:

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

### Quy tắc tải lên

- Phần thân là `multipart/form-data` với đúng một phần, có tên `file`. Mọi phần khác, kể cả `purpose`, đều bị từ chối với `invalid_file`.
- Hãy để HTTP client của bạn đặt `Content-Type`. Đặt thủ công sẽ làm mất multipart boundary.
- Không thêm tham số truy vấn vào URL tải lên.
- Tải lên qua HTTP thay vì dùng helper Files của SDK. `files.create()` của OpenAI SDK luôn gửi `purpose`, nên không thể gọi endpoint này.
- Một lần tải lên bị hết thời gian chờ hoặc ngắt kết nối vẫn có thể đã được lưu. Hãy liệt kê các tệp của bạn trước khi tải lên lại.

## Nơi có thể dùng ID tệp

| Endpoint | Loại tệp | Dạng thức đầu vào bắt buộc | Trường |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, hình ảnh | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, hình ảnh | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Hình ảnh | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Hình ảnh | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Hình ảnh, MP4, âm thanh | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Không hỗ trợ | | |

### 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."}
      ]
    }
  ]
}
```

Với hình ảnh, hãy dùng `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Tệp | Khối nội dung |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Hình ảnh | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Một khối có `file_id` không được đồng thời chứa URL hoặc dữ liệu base64.

### Tạo hình ảnh

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

Phần còn lại của yêu cầu, phản hồi `202` và việc thăm dò được mô tả trong [Tạo hình ảnh](https://openapi.felo.ai/vi/docs/guides/image-generation.md).

### Tạo video

Khung hình đầu và khung hình cuối nằm trong `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..."}
    }
  ]
}
```

Thêm mục thứ hai với `"frame_type": "last_frame"` để có khung hình cuối. Khung hình cuối yêu cầu phải có khung hình đầu.

Tư liệu tham chiếu nằm trong `input_references`. Mỗi mục dùng bộ định vị khớp với loại phương tiện của nó:

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

Mô hình chấp nhận những tổ hợp nào tùy thuộc vào mô hình và kênh. Không thể dùng `frame_images` và `input_references` trong cùng một yêu cầu.

### Quy tắc bộ định vị

- Trong các yêu cầu hình ảnh và video, mỗi đối tượng `image_url`, `video_url` hoặc `audio_url` chứa đúng một trong hai trường `file_id` hoặc `url`, và không có trường nào khác.
- Một mảng có thể kết hợp các mục dùng `file_id` với các mục dùng `url`.
- Tạo hình ảnh và tạo video chỉ chấp nhận các tệp do bạn tải lên. Để dùng lại một hình ảnh đã tạo, hãy truyền `url` đầu ra của nó.
- Yêu cầu có tham chiếu tệp sẽ không được chuyển sang kênh khác khi thất bại. Đừng thử lại trên kênh khác khi chưa kiểm tra lỗi.
- Giữ tệp cho đến khi mọi tác vụ tham chiếu tệp đó đạt trạng thái kết thúc. Xóa tệp sớm hơn có thể làm tác vụ thất bại.

## Kiểm tra khả năng hỗ trợ của mô hình

Tệp đã lưu không tự động dùng được với mọi mô hình. Mô hình phải khai báo dạng thức đầu vào tương ứng trong danh mục công khai:

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

| Để gửi | `input_modalities` phải bao gồm |
|---|---|
| Tệp PDF | `file` |
| Hình ảnh | `image` |
| Tệp MP4 | `video` |
| Tệp âm thanh | `audio` |

Danh sách trống hoặc bị thiếu nghĩa là ID tệp chưa được bật cho mô hình đó. Khi đó yêu cầu thất bại với `file_model_unsupported`. Đừng suy đoán khả năng hỗ trợ từ tên mô hình.

## Giới hạn

| Giới hạn | Giá trị |
|---|---|
| Kích thước tải lên | 100 MiB (104,857,600 byte) mỗi tệp; tệp trống bị từ chối |
| Số byte được tham chiếu mỗi yêu cầu mô hình | Tổng cộng 50,000,000 byte |
| Số tham chiếu mỗi yêu cầu mô hình | 100 |
| Độ dài tên tệp | 255 ký tự |

Tham chiếu cùng một tệp hai lần được tính hai lần vào cả hai giới hạn của yêu cầu. Tệp có kích thước từ 50 MB đến 100 MiB có thể tải lên nhưng không thể tham chiếu trong yêu cầu mô hình. Mô hình hoặc kênh có thể áp dụng giới hạn thấp hơn.

### Loại tệp

Loại tệp được nhận diện từ nội dung của tệp, không phải từ phần mở rộng hay `Content-Type` của phần đó.

| Loại | Định dạng | Có thể tham chiếu trong |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Hình ảnh | PNG, JPEG, GIF, WebP | Messages, Responses, tạo hình ảnh, tạo video |
| Video | MP4 | Tạo video |
| Âm thanh | MP3, WAV, FLAC, OGG | Tạo video |
| Office | DOCX, XLSX, PPTX | Chỉ lưu trữ |
| Văn bản | Văn bản UTF-8, được lưu dưới dạng `text/plain` | Chỉ lưu trữ |

Mọi nội dung khác đều bị từ chối với `invalid_file`.

### Tên tệp

Tên tệp không được chứa `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\` hoặc ký tự điều khiển. `/` được phép dùng làm dấu phân cách, nhưng không được có đoạn trống, `.` và `..`.

## Quản lý tệp

Tệp thuộc về tài khoản của bạn. Mọi khóa API trong tài khoản đều thấy cùng các tệp; các tài khoản khác không thể dùng ID tệp của bạn.

### Liệt kê tệp

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

Kết quả được sắp xếp từ cũ nhất đến mới nhất. Khi `has_more` là `true`, hãy truyền `cursor` được trả về để lấy trang tiếp theo. Không có tính năng tìm kiếm hay lọc theo loại ở phía máy chủ.

### Lấy một tệp

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

### Xóa tệp

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

Việc xóa có hiệu lực ngay lập tức và không thể hoàn tác. `503` nghĩa là việc xóa chưa hoàn tất; hãy gửi lại `DELETE`.

### Tải xuống

Không thể tải xuống các tệp đã tải lên. `GET /api/v1/files/{file_id}/content` trả về `400 file_not_downloadable`, và header `Location` của phản hồi tải lên trỏ đến siêu dữ liệu của tệp, không phải các byte của tệp. Hãy tự giữ bản sao của mọi thứ bạn tải lên.

Để tải xuống nội dung đa phương tiện đã tạo, hãy dùng các URL đã ký trong `outputs` của tác vụ.

## Tham chiếu API

Mọi endpoint đều dùng `Authorization: Bearer YOUR_API_KEY`. Phản hồi thành công là đối tượng JSON thuần, không có lớp bao ngoài.

| Phương thức | Đường dẫn | Trả về |
|---|---|---|
| `POST` | `/api/v1/files` | [Đối tượng tệp](#i-t-ng-t-p) |
| `GET` | `/api/v1/files` | Một [trang tệp](#tham-s-li-t-k) |
| `GET` | `/api/v1/files/{file_id}` | [Đối tượng tệp](#i-t-ng-t-p) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE` và `GET` cho một tệp đơn lẻ từ chối mọi tham số truy vấn với `invalid_query`.

### Đối tượng tệp

| Trường | Kiểu | Mô tả |
|---|---|---|
| `id` | string | ID tệp, có tiền tố `felo_file_`. Dùng nó làm `file_id` |
| `type` | string | Luôn là `file` |
| `source` | string | `upload` cho tệp bạn tải lên, `generated` cho đầu ra của mô hình |
| `filename` | string | Tên được gửi kèm khi tải lên |
| `mime_type` | string | Loại được nhận diện từ nội dung |
| `size_bytes` | integer | Kích thước tính bằng byte |
| `created_at` | string | Dấu thời gian UTC theo ISO 8601 |
| `downloadable` | boolean | `false` đối với tệp đã tải lên |

### Yêu cầu tải lên

| Phần | Bắt buộc | Mô tả |
|---|---|---|
| `file` | Có | Tệp, được gửi dưới dạng phần tệp `multipart/form-data` kèm tên tệp |

Phản hồi có header `Location` chứa URL siêu dữ liệu của tệp.

### Tham số liệt kê

| Tham số | Mặc định | Mô tả |
|---|---|---|
| `limit` | `100` | Kích thước trang, từ 1 đến 1000 |
| `cursor` | | Giá trị `cursor` từ trang trước |
| `after`, `after_id` | | Bí danh của `cursor`. Chỉ gửi một trong ba |
| `order` | `asc` | Chỉ hỗ trợ `asc` |

| Trường phản hồi | Kiểu | Mô tả |
|---|---|---|
| `data` | array | Các đối tượng tệp, cũ nhất trước |
| `first_id` | string hoặc null | ID của tệp đầu tiên trên trang |
| `last_id` | string hoặc null | ID của tệp cuối cùng trên trang |
| `cursor` | string hoặc null | Giá trị cần truyền làm `cursor` cho trang tiếp theo |
| `has_more` | boolean | Có còn trang khác hay không |

## Lỗi

Các endpoint Files, Responses, tạo hình ảnh và tạo video dùng cấu trúc lỗi của 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` là `null` đối với lỗi từ các endpoint Files. Messages trả về dạng lỗi của Anthropic, không có `error.code`. Request ID nằm trong header phản hồi `X-Request-Id`.

Lỗi khi tải lên hoặc quản lý tệp:

| HTTP | `error.code` | Ý nghĩa |
|---|---|---|
| 400 | `invalid_content_type` | Phần thân không phải `multipart/form-data` |
| 400 | `invalid_file` | Không có phần `file`, có phần thừa, tệp trống hoặc nội dung không được hỗ trợ |
| 400 | `invalid_filename` | Tên tệp quá dài hoặc chứa ký tự bị từ chối |
| 413 | `file_too_large` | Tệp vượt quá 100 MiB |
| 400 | `invalid_query` | Tham số truy vấn không được hỗ trợ, hoặc `order` khác `asc` |
| 400 | `invalid_limit` | `limit` nằm ngoài khoảng 1 đến 1000 |
| 400 | `invalid_cursor` | Con trỏ sai định dạng, hoặc có nhiều hơn một con trỏ được gửi |
| 400 | `file_not_downloadable` | `/content` đã được yêu cầu |
| 404 | `file_not_found` | Tệp không tồn tại, đã bị xóa hoặc thuộc tài khoản khác |
| 503 | `file_storage_unavailable` | Lưu trữ tệp tạm thời không khả dụng; thử lại sau |
| 503 | `file_upload_expired` | Tải lên không hoàn tất kịp thời; hãy tải tệp lên lại |

Lỗi khi tham chiếu tệp trong yêu cầu mô hình:

| HTTP | `error.code` | Ý nghĩa |
|---|---|---|
| 400 | `invalid_file_input` | ID sai định dạng, có cả `file_id` và `url` trong một bộ định vị, hoặc nhiều hơn 100 tham chiếu |
| 400 | `unsupported_file_type` | Loại tệp không khớp với vị trí, ví dụ một tệp MP4 trong khối tài liệu |
| 400 | `file_model_unsupported` | Mô hình không khai báo dạng thức đầu vào bắt buộc |
| 400 | `file_input_too_large` | Các tệp được tham chiếu vượt quá tổng cộng 50,000,000 byte |
| 400 | `file_protocol_unsupported` | Một ID tệp đã được gửi đến Chat Completions |
| 404 | `file_not_found` | Tệp không tồn tại, đã bị xóa, thuộc tài khoản khác, hoặc là tệp được tạo sinh gửi đến tạo hình ảnh hoặc tạo video |

Với tạo hình ảnh và tạo video, tệp cũng có thể thất bại sau `202`. Khi đó tác vụ kết thúc ở trạng thái `failed` với một trong các mã này trong `error.code`.

Lỗi xác thực, số dư và giới hạn tốc độ được mô tả trong [Lỗi, giới hạn và thử lại](https://openapi.felo.ai/vi/docs/guides/errors-and-limits.md).

## Liên quan

- [Giao thức và SDK](https://openapi.felo.ai/vi/docs/guides/protocols.md)
- [Tạo hình ảnh](https://openapi.felo.ai/vi/docs/guides/image-generation.md)
- [Tác vụ bất đồng bộ](https://openapi.felo.ai/vi/docs/guides/async-tasks.md)
- [Tham chiếu Model API](https://openapi.felo.ai/vi/docs/model-api)
