--- title: 檔案與上傳 | RunAPI description: 建立、列出、下載及刪除持久性檔案，或從分段上傳組件組合檔案。 url: https://runapi.ai/zh-TW/docs/resources/files.md canonical: https://runapi.ai/zh-TW/docs/resources/files locale: zh-TW --- > HTML 版本: https://runapi.ai/zh-TW/docs/resources/files > 代理程式網站索引: https://runapi.ai/llms.txt # 檔案與上傳 Files API 儲存不可變、以帳戶為範圍的 `user_data`、`batch` 及 `batch_output` File，並返回穩定的 File ID，而非儲存 URL。當 API 接受可重複使用的 File 資源時，請使用 File ID；當您的應用程式需要存取已儲存的原始位元組時，請使用內容端點。 ## 選擇上傳流程 * 使用 `POST /v1/files` 透過單一 multipart 請求建立 File。已完成的 `user_data` File 最多可包含 `52,428,800` 位元組。 * 使用 `POST /v1/files` 並設定 `purpose=batch`，可直接上傳最大 `95,000,000` 位元組的批次輸入。 * 使用 Uploads API 先傳送 Parts，再組合成最終的 File。每個 Part 最多可包含 `67,108,864` 位元組；已完成的 `user_data` File 上限為 `52,428,800` 位元組，已完成的 `batch` File 上限為 `209,715,200` 位元組。未完成的 Upload 將在一小時後過期。 * 作用中的 Files 與進行中的預留空間共用帳戶儲存空間上限 `5,368,709,120` 位元組。 `POST /api/v1/files` 是一個獨立的暫時上傳流程，會回傳一個暫時 URL。SDK 的 `files.create` 和 CLI 的 `runapi files create` 繼續使用該流程。當您需要持久性 File 物件時，請使用 `files.createFile` 或 `files.create_file`，或 CLI 的 `runapi files create-file`。 ## 對請求進行身分驗證 檔案與上傳使用標準 RunAPI API 金鑰。請以 Bearer 權杖方式傳送： ```shell export RUNAPI_API_KEY="runapi_..." ``` 每個檔案、上傳、組件及內容請求都限定於已驗證身分的帳戶。屬於其他帳戶的 ID 將回傳 `404`，且不會透露該資源是否存在。 ## 使用相容用戶端建立檔案 將支援 OpenAI 的用戶端指向 RunAPI `/v1` 基底 URL，無需任何 RunAPI 專屬的請求欄位： ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["RUNAPI_API_KEY"], base_url="https://runapi.ai/v1", ) with open("knowledge.pdf", "rb") as source: file = client.files.create(file=source, purpose="user_data") metadata = client.files.retrieve(file.id) client.files.content(file.id).write_to_file("knowledge-copy.pdf") client.files.delete(file.id) ``` 返回的 File 絕不包含儲存識別碼、後端或持有者 URL。 ## API 參考 * [持久性 Files API](https://runapi.ai/zh-TW/docs/api/protocol/files.md) 涵蓋 File 物件以及建立、列出、擷取、取得內容及刪除等操作。 * [Uploads API](https://runapi.ai/zh-TW/docs/api/protocol/uploads.md) 涵蓋 Upload 物件以及建立、新增分段、完成及取消等操作。 * [Batches API](https://runapi.ai/zh-TW/docs/api/protocol/batches.md) 涵蓋審核批次的建立、狀態查詢、列出及取消等操作。 ## 以批次方式執行內容審核 建立一個 JSONL 輸入檔案，每行包含一個審核請求。每行使用相容的批次結構：`custom_id`、`method`、`url` 設為 `/v1/moderations`，以及包含審核模型與輸入內容的 `body`。`purpose=batch` 的檔案最多可包含 50,000 個請求。批次功能目前接受 `/v1/moderations` 端點，完成時間窗口為 `24h`。 ```shell INPUT_FILE_ID=$(curl -sS https://runapi.ai/v1/files \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -F purpose=batch \ -F file=@moderation.jsonl | jq -r .id) BATCH_ID=$(curl -sS https://runapi.ai/v1/batches \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg file "$INPUT_FILE_ID" '{input_file_id:$file,endpoint:"/v1/moderations",completion_window:"24h"}')" \ | jq -r .id) curl -sS "https://runapi.ai/v1/batches/$BATCH_ID" \ -H "Authorization: Bearer $RUNAPI_API_KEY" ``` 使用 `GET /v1/batches` 列出工作項目，重複呼叫 `GET /v1/batches/{batch_id}` 直到狀態進入終止狀態，或在仍執行中時呼叫 `POST /v1/batches/{batch_id}/cancel`。完成的輸出與錯誤 JSONL 會以 `batch_output` Files 形式公開；使用 `GET /v1/files/{file_id}` 取得其中繼資料，並使用 `GET /v1/files/{file_id}/content` 取得確切的位元組內容。 ## 分段上傳生命週期 使用最終位元組數、檔案名稱、MIME 類型及 `purpose=user_data` 建立上傳。新增一個或多個部分，然後按組合順序將其 ID 傳遞至 `complete`。完成後返回包含已完成檔案的上傳物件。 ```shell UPLOAD_ID=$(curl -sS https://runapi.ai/v1/uploads \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"bytes":1048576,"filename":"archive.bin","mime_type":"application/octet-stream","purpose":"user_data"}' \ | jq -r .id) PART_ID=$(curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/parts" \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -F data=@archive.part-01 | jq -r .id) curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/complete" \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"part_ids\":[\"$PART_ID\"]}" ``` 使用 `POST /v1/uploads/{upload_id}/cancel` 取消未完成的上傳。重複相同的完成意圖或取消操作是安全的；若另一個終態結果已先確定，則競爭的完成、取消或過期操作將返回 `409 upload_state_conflict`。 ## CLI 與 SDK 資源 CLI 提供完整的生命週期操作： ```shell runapi files create-file knowledge.pdf runapi files list --order desc runapi files retrieve file_123 runapi files content file_123 --output knowledge-copy.pdf runapi files delete file_123 runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream runapi uploads add-part upload_123 archive.part-01 runapi uploads complete upload_123 --part-id part_123 runapi uploads cancel upload_123 ``` 每個 Provider Client 皆公開 `files` 與 `uploads`。JavaScript 和 PHP 使用 `createFile` / `deleteFile` / `addPart`；Python 和 Ruby 使用 `create_file` / `delete_file` / `add_part`；Go 使用 `CreateFile` / `DeleteFile` / `AddPart`；Java 使用 `createFile` / `deleteFile` / `addPart`。List、retrieve、content、create、complete 及 cancel 遵循 各語言的一般命名慣例。請參閱 [SDK](https://runapi.ai/zh-TW/docs/resources/sdks.md)以了解套件安裝方式。 ## 生命週期行為 檔案內容不可變更。刪除檔案會立即將其從活躍列表中移除，並排程儲存空間清理。上傳完成時僅依提供的順序組合組件，且成功完成後會建立一個檔案。在重試不確定的完成回應時，請保持原始組件 ID 的順序。 --- ## RunAPI 的更多內容 - [首頁](https://runapi.ai/zh-TW/.md) - [模型目錄](https://runapi.ai/zh-TW/models.md) - [價格](https://runapi.ai/zh-TW/pricing.md) - [提供商](https://runapi.ai/zh-TW/models) - [文件](https://runapi.ai/zh-TW/docs/guides) - [SDK](https://runapi.ai/zh-TW/sdk.md) - [CLI](https://runapi.ai/zh-TW/cli.md) - [MCP Server](https://runapi.ai/zh-TW/mcp.md) - [Claude Code 與 Cursor](https://runapi.ai/zh-TW/claude-code-vs-cursor.md) - [Cursor API 設定](https://runapi.ai/zh-TW/cursor-api-setup.md) - [RunAPI 與 OpenRouter](https://runapi.ai/zh-TW/openrouter-alternative.md) - [企業版](https://runapi.ai/zh-TW/contact.md) - [聯絡我們](https://runapi.ai/zh-TW/contact.md) - [服務條款](https://runapi.ai/zh-TW/terms.md) - [隱私權](https://runapi.ai/zh-TW/privacy.md) - [代理程式網站索引](https://runapi.ai/llms.txt) 聯絡我們: contact@runapi.ai ## 結構化資料 ```json [ { "@context": "https://schema.org", "inLanguage": "zh-TW", "@type": "WebSite", "name": "RunAPI", "url": "https://runapi.ai/zh-TW", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://runapi.ai/zh-TW/models?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@context": "https://schema.org", "inLanguage": "zh-TW", "@type": "Organization", "name": "RunAPI", "url": "https://runapi.ai/zh-TW", "logo": { "@type": "ImageObject", "url": "https://runapi.ai/zh-TWicon.svg" }, "sameAs": [ "https://github.com/runapi-ai" ] }, { "@context": "https://schema.org", "inLanguage": "zh-TW", "@type": "TechArticle", "headline": "檔案與上傳", "description": "建立、列出、下載及刪除持久性檔案，或從分段上傳組件組合檔案。", "url": "https://runapi.ai/zh-TW/docs/resources/files", "mainEntityOfPage": "https://runapi.ai/zh-TW/docs/resources/files" } ] ```