--- title: 创建 File | RunAPI description: 将一个 multipart user_data 或 batch File 流式写入持久存储。 url: https://runapi.ai/zh-CN/docs/api/protocol/files/create.md canonical: https://runapi.ai/zh-CN/docs/api/protocol/files/create locale: zh-CN --- > HTML version: https://runapi.ai/zh-CN/docs/api/protocol/files/create > Site index for agents: https://runapi.ai/llms.txt # 创建 File 将一个 multipart user_data 或 batch File 流式写入持久存储。 ## 端点 POST /v1/files 基础 URL: https://runapi.ai API 版本: v1 身份验证: Authorization: Bearer YOUR_API_KEY ## 请求 只能在列出的请求位置发送值。 ### multipart/form-data ```json { "file": { "description": "File bytes to store.", "format": "binary", "required": true, "type": "string" }, "purpose": { "default": "user_data", "description": "File purpose.", "enum": [ "user_data", "batch" ], "required": true, "type": "string" } } ``` ## 成功响应 HTTP 200 - POST /v1/files ```json { "bytes": 1048576, "created_at": 1785196800, "filename": "knowledge.pdf", "id": "file_abc123", "object": "file", "purpose": "user_data" } ``` ## 错误响应 (401) HTTP 401 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "authentication_error", "message": "Missing API key", "param": null, "type": "authentication_error" } } ``` ## 错误响应 (400) HTTP 400 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "invalid_request_error", "message": "Malformed request", "param": null, "type": "invalid_request_error" } } ``` ## 错误响应 (404) HTTP 404 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "not_found", "message": "File not found", "param": null, "type": "invalid_request_error" } } ``` ## 错误响应 (409) HTTP 409 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "upload_state_conflict", "message": "Upload state conflict", "param": null, "type": "invalid_request_error" } } ``` ## 错误响应 (413) HTTP 413 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "file_too_large", "message": "File size exceeds the maximum allowed size", "param": "file", "type": "invalid_request_error" } } ``` ## 错误响应 (422) HTTP 422 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "invalid_upload", "message": "Upload request rejected", "param": null, "type": "invalid_request_error" } } ``` ## 错误响应 (502) HTTP 502 ### 响应 Schema ```json { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "message", "type" ], "type": "object" } }, "required": [ "error" ], "type": "object" } ``` ### 响应示例 ```json { "error": { "code": "storage_write_failed", "message": "File storage failed", "param": null, "type": "server_error" } } ``` ## cURL 示例 ### curl ```curl curl -X POST https://runapi.ai/v1/files \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'file=@./knowledge.pdf' \ -F 'purpose=user_data' ``` ## 相关参考 - [持久 File](https://runapi.ai/docs/api/protocol/files.md) - [File 对象](https://runapi.ai/docs/api/protocol/files/object.md) --- ## More from RunAPI - [Home](https://runapi.ai/.md) - [模型](https://runapi.ai/zh-CN/models.md) - [AI 视频 API 对比](https://runapi.ai/zh-CN/ai-video-api-comparison.md) - [OpenClaw 集成](https://runapi.ai/zh-CN/openclaw.md) - [OpenClaw 最佳 API](https://runapi.ai/zh-CN/best-api-for-openclaw.md) - [OpenClaw 图片生成](https://runapi.ai/zh-CN/openclaw-image-generation.md) - [Hermes 智能体集成](https://runapi.ai/zh-CN/hermes-agent.md) - [定价](https://runapi.ai/zh-CN/pricing.md) - [Claude API 定价](https://runapi.ai/zh-CN/claude-api-pricing.md) - [ChatGPT API 定价](https://runapi.ai/zh-CN/chatgpt-api-pricing.md) - [OpenAI API 定价](https://runapi.ai/zh-CN/openai-api-pricing.md) - [Gemini API 定价](https://runapi.ai/zh-CN/gemini-api-pricing.md) - [Claude Code 定价](https://runapi.ai/zh-CN/claude-code-pricing.md) - [Claude Code API](https://runapi.ai/zh-CN/claude-code-api.md) - [Claude Code 对比 Cursor](https://runapi.ai/zh-CN/claude-code-vs-cursor.md) - [Claude Max 对比 API](https://runapi.ai/zh-CN/claude-max-vs-api.md) - [Requesty 替代方案](https://runapi.ai/zh-CN/requesty-alternative.md) - [文档](https://runapi.ai/zh-CN/docs/guides) - [SDK](https://runapi.ai/zh-CN/sdk.md) - [Skills](https://runapi.ai/zh-CN/skills.md) - [MCP Server](https://runapi.ai/zh-CN/mcp.md) - [CLI](https://runapi.ai/zh-CN/cli.md) - [反馈](https://runapi.ai/) - [联系](mailto:support@runapi.ai) - [服务条款](https://runapi.ai/zh-CN/terms.md) - [隐私政策](https://runapi.ai/zh-CN/privacy.md) - [Site index for agents](https://runapi.ai/llms.txt) Contact: contact@runapi.ai ## Structured data ```json [ { "@context": "https://schema.org", "inLanguage": "zh-CN", "@type": "WebSite", "name": "RunAPI", "url": "https://runapi.ai/zh-CN", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://runapi.ai/zh-CN/models?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@context": "https://schema.org", "inLanguage": "zh-CN", "@type": "Organization", "name": "RunAPI", "url": "https://runapi.ai/zh-CN", "logo": { "@type": "ImageObject", "url": "https://runapi.ai/zh-CNicon.svg" }, "sameAs": [ "https://github.com/runapi-ai" ] }, { "@context": "https://schema.org", "inLanguage": "zh-CN", "@type": "TechArticle", "headline": "创建 File", "description": "将一个 multipart user_data 或 batch File 流式写入持久存储。", "url": "https://runapi.ai/zh-CN/docs/api/protocol/files/create", "mainEntityOfPage": "https://runapi.ai/zh-CN/docs/api/protocol/files/create" } ] ```