# 檔案上傳

檔案上傳一次，之後在 Messages、Responses、圖片生成和影片生成請求中以 ID 引用。

檔案上傳一次，之後在模型請求中按 ID 引用，不必每次把同一份內容轉成 base64 重送，也不必把檔案放到公開 URL 上。

檔案 ID 可用於 Messages、Responses、圖片生成和影片生成，不能用於 Chat Completions。

## 開始之前

- API key。見[認證](https://openapi.felo.ai/zh-TW/docs/authentication.md)。
- Base URL：`https://openapi.felo.ai`。
- 一個接受對應檔案類型的模型。見[檢查模型支援](#檢查模型支援)。

## 快速開始

### 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`。
- `Content-Type` 交給 HTTP 用戶端產生。手動設定會遺失 multipart boundary。
- 上傳 URL 不要帶查詢參數。
- 直接用 HTTP 上傳，不要用 SDK 的 Files 方法。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/zh-TW/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 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`。成功回應就是 JSON 物件本身，沒有外層信封。

| 方法 | 路徑 | 回傳 |
|---|---|---|
| `POST` | `/api/v1/files` | [檔案物件](#檔案物件) |
| `GET` | `/api/v1/files` | [一頁檔案](#列表參數) |
| `GET` | `/api/v1/files/{file_id}` | [檔案物件](#檔案物件) |
| `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 | 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 錯誤信封：

```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.code`。request ID 在 `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` | 向 Chat Completions 傳送了檔案 ID |
| 404 | `file_not_found` | 檔案不存在、已刪除、屬於其他帳號，或把生成的檔案傳給圖片或影片生成 |

在圖片和影片生成中，檔案也可能在回傳 `202` 之後才失敗。此時任務會以 `failed` 結束，`error.code` 為上述代碼之一。

認證、餘額和限流錯誤見[錯誤、限流與重試](https://openapi.felo.ai/zh-TW/docs/guides/errors-and-limits.md)。

## 相關

- [協定與 SDK](https://openapi.felo.ai/zh-TW/docs/guides/protocols.md)
- [圖片生成](https://openapi.felo.ai/zh-TW/docs/guides/image-generation.md)
- [非同步任務](https://openapi.felo.ai/zh-TW/docs/guides/async-tasks.md)
- [Model API 參考](https://openapi.felo.ai/zh-TW/docs/model-api)
