> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 支援 Files API 上傳檔案嗎？

> API易 不提供 Files API，也不提供依賴它的 Batch、Assistants 等介面。調 /v1/files 會報「Current group … has no available channels for model」。圖片、PDF 等檔案請用 base64 或 URL 直接放進請求裡。

## 簡短回答

**不支援。** API易 不提供 Files API，也就是先上傳檔案、拿到 `file_id`、再在請求裡引用的那種用法。依賴檔案上傳的幾類介面同樣不提供：

| 介面 | 路徑 | 呼叫結果 |
| - | - | - |
| OpenAI Files API | `/v1/files` | 503，報「當前分組沒有可用渠道」 |
| OpenAI Assistants API | `/v1/assistants`、`/v1/threads` | 503，同上 |
| OpenAI Batch API | `/v1/batches` | 404 `Invalid URL` |
| OpenAI Vector Stores、Uploads | `/v1/vector_stores`、`/v1/uploads` | 404 `Invalid URL` |
| Claude Message Batches | `/v1/messages/batches` | 404 `Invalid URL` |
| Gemini Files API | `client.files.upload()`、`/v1beta/files` | 不可用 |

**替代做法**：把圖片、PDF 等檔案用 base64 或 URL **直接放進對話請求裡**，各家模型都支援這種內聯寫法，見下文。

## 報錯是什麼意思

調 `/v1/files` 時會收到：

```json theme={null}
{
  "error": {
    "message": "Current group default has no available channels for model  under billing mode [pay-as-you-go, pay-per-request] (request id: …)",
    "type": "shell_api_error"
  }
}
```

注意 `for model` 後面是空的。平臺按模型名給請求分配渠道，上傳檔案的請求裡沒有模型名，平臺找不到對應渠道，就報了這條錯誤。它的真實意思是**平臺不提供這個介面**，跟分組、餘額、令牌權限都無關，換分組或重試也不會變好。

在對話請求裡引用不存在的 `file_id`，報錯會因介面而異，例如：

| 寫法 | 報錯 |
| - | - |
| `/v1/chat/completions` 裡傳 `file.file_id` | `Files [file-xxx] were not found` |
| `/v1/responses` 裡傳 `input_file.file_id` | `Invalid 'input[0].content[0].file_id'` |

> [!NOTE]
>
> 如果你用的是 OpenAI、Anthropic、Google 的官方 SDK，又把 `base_url` 換成了 API易，那麼 `client.files.create()`、`client.files.upload()`、`client.batches.create()` 這類方法都會失敗，請改成下文的內聯寫法。

## 替代做法：把檔案直接放進請求

**OpenAI 格式**

**圖片**：`image_url` 裡傳公網 URL，或 `data:image/png;base64,...`。

**PDF**：`/v1/responses` 用 `input_file` 的 `file_data`；`/v1/chat/completions` 用 `file` 型別的 `file_data`。

```json theme={null}
{
  "model": "gpt-5.4-mini",
  "input": [{
    "role": "user",
    "content": [
      {
        "type": "input_file",
        "filename": "report.pdf",
        "file_data": "data:application/pdf;base64,JVBERi0xLjQK..."
      },
      { "type": "input_text", "text": "總結這份檔案" }
    ]
  }]
}
```

**Claude 格式**

**圖片**：`image` 塊，`source.type` 用 `base64` 或 `url`。

**PDF**：`document` 塊，`source.type` 用 `base64`。`source.type = "file"` 依賴 Files API，不可用。

```json theme={null}
{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "document",
        "source": {
          "type": "base64",
          "media_type": "application/pdf",
          "data": "JVBERi0xLjQK..."
        }
      },
      { "type": "text", "text": "總結這份檔案" }
    ]
  }]
}
```

**Gemini 格式**

**圖片、PDF、音影片**：`inline_data` 傳 base64，單個檔案不超過 20MB；圖片也可以用 `file_data.file_uri` 傳公網 URL。

```json theme={null}
{
  "contents": [{
    "role": "user",
    "parts": [
      {
        "inline_data": {
          "mime_type": "application/pdf",
          "data": "JVBERi0xLjQK..."
        }
      },
      { "text": "總結這份檔案" }
    ]
  }]
}
```

大影片的處理方法見 [影片理解 API](/zh-Hant/api-capabilities/video-understanding)。

以上三種寫法已於 2026-10-22 實測：同一份 PDF 分別經 `/v1/responses`、`/v1/chat/completions`、Claude `/v1/messages`、Gemini `generateContent` 傳入，模型都正確讀出了檔案內容。

> [!TIP]
>
> 內聯寫法的代價是每次請求都要重新帶上檔案，請求體會變大。同一份檔案要問很多輪時，可以把它轉成文本後放進提示詞，或者利用各家的快取能力降低重複輸入的費用，見 [API易支援快取計費嗎？](/zh-Hant/faq/cache-billing)。

## 需要批次處理怎麼辦

平臺沒有 Batch API，批次任務請在客戶端自己併發傳送普通請求，併發上限見 [API 可以開多少併發？](/zh-Hant/faq/api-concurrency)。普通請求按正常價格計費，沒有官方 Batch API 那種非同步折扣。

## 相關文件

> **[影片理解 API](/zh-Hant/api-capabilities/video-understanding)**
>
> 各模型的影片傳入方式與大小限制

> **[Base URL 怎麼填？/v1、根域名、/v1beta 有什麼區別？](/zh-Hant/faq/base-url-config)**
>
> OpenAI / Claude / Gemini 三種格式分別怎麼填

> **[API 可以開多少併發？](/zh-Hant/faq/api-concurrency)**
>
> 批次任務在客戶端併發傳送

> **[模型呼叫報錯怎麼排查？](/zh-Hant/faq/model-error-troubleshooting)**
>
> 按錯誤型別逐項對號入座


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.