> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/api-integration/file-library-resumable-upload.md).

# 檔案庫續傳上傳 API

以分塊上傳 session 將檔案寫入檔案庫，使用伺服器 offset 恢復傳輸、SHA-256 驗證完整性，並處理完成與取消。

整合端需要上傳較大的檔案，或在網路中斷後繼續傳輸時，可使用檔案庫的上傳 session。這套流程接受 **1 byte 至 500 MiB（524,288,000 bytes）** 的檔案；一般直接上傳與版本直接上傳仍維持 10 MiB 上限，不能套用本頁的 500 MiB 限制。

例如，文件整合服務要把一份大型訓練教材存入檔案庫。服務先計算整份檔案的 SHA-256，再建立 session、逐塊傳送；途中斷線時讀回伺服器進度，從回傳的位移接續，最後請伺服器驗證並完成檔案。

## 前提與路徑 <a href="#prerequisites-and-path" id="prerequisites-and-path"></a>

請以 `Authorization: Api-Key <您的 API 金鑰>` 驗證身分；金鑰取得方式見[快速上手](https://docs.maiagent.ai/tech/api-integration/quickstart.md)。

組織必須啟用檔案庫，呼叫者須為已驗證成員、具檔案庫權限，並可寫入目標空間。目標必須是資料夾，不能直接上傳到空間根目錄；外部來源同步資料夾及其子資料夾是唯讀目標，也不能上傳。

本頁以此路徑為基底，以下以 `{base}` 表示：

```
/api/v1/file-library/folders/{folderId}/upload-sessions/
```

## 建立或找回 session <a href="#create-session" id="create-session"></a>

向 `{base}` 送 `POST`，使用 JSON：

| 欄位                | 必填 | 說明                                |
| ----------------- | -- | --------------------------------- |
| `clientId`        | 是  | 用戶端產生的 UUID；恢復同一次上傳時沿用            |
| `filename`        | 是  | 檔案名稱，不可包含目錄路徑，且副檔名須為檔案庫允許的格式      |
| `sha256`          | 是  | 整份檔案的 SHA-256，64 位小寫十六進位字元        |
| `size`            | 是  | 整份檔案的 bytes 數，不接受空檔               |
| `contentType`     | 否  | MIME 類型，預設空字串                     |
| `collisionPolicy` | 否  | `ask`（預設）、`keep_both` 或 `replace` |
| `replaceFileId`   | 否  | 使用 `replace` 時指定要取代的檔案            |

允許的副檔名為 `pdf`、`doc`、`docx`、`ppt`、`pptx`、`xls`、`xlsx`、`csv`、`txt`、`md`、`json`、`html`、`png`、`jpg`、`jpeg`、`gif`、`webp`、`mp3`、`wav`、`m4a`、`mp4`、`dxf`，大小寫不拘；無副檔名或不支援的格式會被拒絕。

同一使用者、同一資料夾、同一 `clientId` 會找回既有 session；`filename`、`sha256`、`size` 或 `contentType` 與原值不同時會拒絕。建立與找回都回 `201`。

回應包含 `id`、`folderId`、`filename`、`sha256`、`size`、`offset`、`chunkSize`、`completed` 與 `completedFileId`。`offset` 是下一塊應傳的 byte 位移；`chunkSize` 為 2 MiB（2,097,152 bytes）。

## 傳送與恢復 <a href="#send-and-resume" id="send-and-resume"></a>

1. 向 `{base}{sessionId}/` 送 `PATCH`，使用 `multipart/form-data`，帶非負整數 `offset` 與二進位檔案欄位 `chunk`。
2. 每塊大於 0 且不超過 `chunkSize`；只有最後一塊可以短於 `chunkSize`。依序傳送，位移須等於伺服器目前的 `offset`，且總量不得超過宣告的 `size`。
3. 每次成功回 `200` 的 session，使用回傳的 `offset` 決定下一塊。若不確定上一次是否送達，先對 `{base}{sessionId}/` 送 `GET` 讀回進度。

先前已接收的塊可以重送，但位移必須落在已記錄的塊邊界，且位移、大小及內容 SHA-256 均與原塊一致，才會回既有進度。不要平行亂序上傳。

每塊的雜湊由伺服器計算；PATCH 不需要另外帶塊雜湊。session 自建立起 24 小時有效，不存在、非本人或過期時回 `404`。

## 完成與取消 <a href="#complete-and-cancel" id="complete-and-cancel"></a>

全部 bytes 傳完後，向 `{base}{sessionId}/complete/` 送 `POST`，未需處理同名檔案時可用空 JSON 物件 `{}`。伺服器重新檢查各塊的位移、大小與 SHA-256，再比對整份檔案的 SHA-256；驗證通過才完成，成功回 `201` 的檔案物件。

完成時仍會重新檢查同名衝突、容量與版本，因此傳完所有塊不代表檔案已經完成：

* `ask` 遇同名回 `409 duplicate_name`，附 `existingFileId` 與 `currentVersionNumber`。
* `keep_both` 會為檔名加數字尾碼。
* `replace` 必須指定 `replaceFileId`；完成時另帶 `expectedVersionNumber`，避免覆寫別人剛更新的版本。完成請求必須再次帶 `collisionPolicy: "replace"` 與 `replaceFileId`，`expectedVersionNumber` 須帶最近讀取或 `409` 回應中的 `currentVersionNumber`：已有版本時為正整數，尚無版本時明確傳 JSON `null`，不能省略或自行猜測版本號。

{% hint style="warning" %}
建立 session 時的同名策略不會保存在 session。若選擇 `keep_both` 或 `replace`，完成請求也必須再次送出該策略與必要欄位；未指定時會重新使用 `ask`。
{% endhint %}

已完成的 session 再送 complete 會回原本完成的檔案，不會新增第二份；原檔案已刪除或目前不可見時回 `404`。

取消未完成的 session，可向 `{base}{sessionId}/` 送 `DELETE`，成功回 `204`；完成後不能取消。若要處理已完成的檔案，應使用檔案管理流程。

{% hint style="info" %}
本流程寫入檔案庫，不是對話附件上傳。若要把檔案交給對話中的 Agent，請參閱 [對話附件上傳與下載](https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/conversation-attachments.md)。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/api-integration/file-library-resumable-upload.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
