--- title: 建立文件上傳 | RunAPI description: 上傳一個本地檔案、遠端 HTTPS URL 或 base64 來源，並接收臨時 URL。 url: https://runapi.ai/zh-HK/docs/api/files/create.md canonical: https://runapi.ai/zh-HK/docs/api/files/create locale: zh-HK --- > HTML 版本: https://runapi.ai/zh-HK/docs/api/files/create > 智能代理網站索引: https://runapi.ai/llms.txt # 建立文件上傳 上傳一個本地檔案、遠端 HTTPS URL 或 base64 來源，並接收臨時 URL。 ## 端點 POST /api/v1/files 基礎 URL: https://runapi.ai API 版本: v1 身份驗證: Authorization: Bearer YOUR_API_KEY ## 請求 僅在列出的請求位置傳送值。 ### application/json - Base64 source ```json { "file_name": { "description": "已建立的檔案上傳的可選檔案名稱。", "required": false, "type": "string" }, "source": { "description": "Base64 編碼的來源位元組。", "properties": { "data": { "description": "Base64 資料", "required": true, "type": "string" }, "type": { "description": "選擇 base64 來源表示法。", "required": true, "type": "string" } }, "required": true, "type": "object" } } ``` ### application/json - URL source ```json { "file_name": { "description": "已建立的檔案上傳的可選檔案名稱。", "required": false, "type": "string" }, "source": { "description": "用於下載的遠端 HTTPS 來源。", "properties": { "type": { "description": "選擇 URL 來源表示法。", "required": true, "type": "string" }, "url": { "description": "可供下載的公開 HTTPS URL。", "format": "uri", "required": true, "type": "string" } }, "required": true, "type": "object" } } ``` ### multipart/form-data ```json { "file": { "description": "要上傳的本地檔案位元組。", "format": "binary", "required": true, "type": "string" }, "file_name": { "description": "已建立的檔案上傳的可選檔案名稱。", "required": false, "type": "string" } } ``` ## 成功回應 HTTP 201 - POST /api/v1/files ```json { "created_at": "2026-07-27T10:00:00.000Z", "expires_at": "2026-07-27T11:00:00.000Z", "file_name": "mask.png", "mime_type": "image/png", "size_bytes": 204800, "url": "https://file.runapi.ai/temp/user-uploads/mask.png" } ``` ## 錯誤回應（401） HTTP 401 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Authentication required" } ``` ## 錯誤回應（403） HTTP 403 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Standard API key required" } ``` ## 錯誤回應（400） HTTP 400 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Only HTTPS URLs are allowed" } ``` ## 錯誤回應（408） HTTP 408 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Download timeout" } ``` ## 錯誤回應（413） HTTP 413 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "File size exceeds the maximum allowed size" } ``` ## 錯誤回應（415） HTTP 415 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "This content type is not supported" } ``` ## 錯誤回應（422） HTTP 422 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "File upload failed. Please try again." } ``` ## 錯誤回應（429） HTTP 429 ### 回應結構 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Too many file uploads for this account. Please retry later." } ``` ## cURL 範例 ### curl ```curl curl -X POST https://runapi.ai/api/v1/files \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"source":{"type":"url","url":"https://cdn.runapi.ai/public/samples/mask.png"},"file_name":"mask.png"}' ``` ## 相關參考資料 - [檔案](https://runapi.ai/zh-HK/docs/api/files.md) - [檔案上傳物件](https://runapi.ai/zh-HK/docs/api/files/object.md) --- ## RunAPI 的更多內容 - [首頁](https://runapi.ai/zh-HK/.md) - [模型目錄](https://runapi.ai/zh-HK/models.md) - [收費](https://runapi.ai/zh-HK/pricing.md) - [服務商](https://runapi.ai/zh-HK/models) - [文件](https://runapi.ai/zh-HK/docs/guides) - [SDK](https://runapi.ai/zh-HK/sdk.md) - [CLI](https://runapi.ai/zh-HK/cli.md) - [MCP Server](https://runapi.ai/zh-HK/mcp.md) - [Claude Code 與 Cursor](https://runapi.ai/zh-HK/claude-code-vs-cursor.md) - [Cursor API 設定](https://runapi.ai/zh-HK/cursor-api-setup.md) - [RunAPI 與 OpenRouter](https://runapi.ai/zh-HK/openrouter-alternative.md) - [企業版](https://runapi.ai/zh-HK/contact.md) - [聯絡](https://runapi.ai/zh-HK/contact.md) - [條款](https://runapi.ai/zh-HK/terms.md) - [私隱](https://runapi.ai/zh-HK/privacy.md) - [智能代理網站索引](https://runapi.ai/llms.txt) 聯絡我們: contact@runapi.ai ## 結構化資料 ```json [ { "@context": "https://schema.org", "inLanguage": "zh-HK", "@type": "WebSite", "name": "RunAPI", "url": "https://runapi.ai/zh-HK", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://runapi.ai/zh-HK/models?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@context": "https://schema.org", "inLanguage": "zh-HK", "@type": "Organization", "name": "RunAPI", "url": "https://runapi.ai/zh-HK", "logo": { "@type": "ImageObject", "url": "https://runapi.ai/zh-HKicon.svg" }, "sameAs": [ "https://github.com/runapi-ai" ] }, { "@context": "https://schema.org", "inLanguage": "zh-HK", "@type": "TechArticle", "headline": "建立文件上傳", "description": "上傳一個本地檔案、遠端 HTTPS URL 或 base64 來源，並接收臨時 URL。", "url": "https://runapi.ai/zh-HK/docs/api/files/create", "mainEntityOfPage": "https://runapi.ai/zh-HK/docs/api/files/create" } ] ```