--- title: Files 与 Uploads | RunAPI description: 创建、列出、下载和删除持久 File，或通过多个 Upload Part 组装 File。 url: https://runapi.ai/zh-CN/docs/resources/files.md canonical: https://runapi.ai/zh-CN/docs/resources/files locale: zh-CN --- > HTML version: https://runapi.ai/zh-CN/docs/resources/files > Site index for agents: https://runapi.ai/llms.txt # Files 与 Uploads Files API 保存不可变、按 Account 隔离的 `user_data`、`batch` 和 `batch_output` File，并返回稳定的 File ID，而不是存储 URL。当 API 接受可复用 File resource 时传入 File ID；应用需要原始内容时，通过 content endpoint 读取完全一致的字节。 ## 选择上传流程 * 使用 `POST /v1/files` 通过一次 multipart 请求创建 File。完成后的 `user_data` File 最大为 `52,428,800` bytes。 * 使用 `POST /v1/files` 并设置 `purpose=batch`，直接创建最大 `95,000,000` bytes 的 Batch 输入 File。 * 使用 Uploads API 先发送多个 Part，再组装最终 File。每个 Part 最大为 `67,108,864` bytes；完成后的 `user_data` File 最大为 `52,428,800` bytes，`batch` File 最大为 `209,715,200` bytes；未完成的 Upload 会在一小时后过期。 * Active File 和进行中的 reservation 共用 Account 存储上限 `5,368,709,120` bytes。 `POST /api/v1/files` 是独立的临时上传流程，返回临时 URL。SDK `files.create` 与 CLI `runapi files create` 会继续使用该流程。需要持久 File object 时，请使用 `files.createFile` 或 `files.create_file`，或者 CLI `runapi files create-file`。 ## 认证请求 Files 与 Uploads 使用标准 RunAPI API Key。请通过 Bearer token 发送： ```shell export RUNAPI_API_KEY="runapi_..." ``` 每个 File、Upload、Part 和 content 请求都按当前认证 Account 隔离。访问其他 Account 拥有的 ID 会返回 `404`，且不会泄露该 resource 是否存在。 ## 使用兼容客户端创建 File 将 OpenAI-compatible client 指向 RunAPI `/v1` base 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 不会包含 storage identifier、backend 或 bearer URL。 ## API Reference * [Persistent Files API](https://runapi.ai/zh-CN/docs/api/protocol/files) 包含 File 对象及 create、list、retrieve、content 和 delete operation。 * [Uploads API](https://runapi.ai/zh-CN/docs/api/protocol/uploads) 包含 Upload 对象及 create、add-part、complete 和 cancel operation。 * [Batches API](https://runapi.ai/zh-CN/docs/api/protocol/batches) 包含 Moderation Batch 的创建、状态查询、列表和取消 operation。 ## 批量执行 Moderation 创建 JSONL 输入 File，每行包含一个 moderation request。每行使用兼容 Batch 格式：`custom_id`、`method`、值为 `/v1/moderations` 的 `url`，以及包含 moderation model 和 input 的 `body`。`purpose=batch` File 最多包含 50,000 个 request。当前 Batch capability 只接受 `/v1/moderations` endpoint 和 `24h` completion window。 ```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` 列出 Batch，重复 `GET /v1/batches/{batch_id}` 直到状态进入终态；仍在运行时可调用 `POST /v1/batches/{batch_id}/cancel`。完成后的 output 和 error JSONL 会作为 `batch_output` File 提供；使用 `GET /v1/files/{file_id}` 获取 metadata，使用 `GET /v1/files/{file_id}/content` 读取完整 bytes。 ## Multipart Upload 生命周期 创建 Upload 时提供最终 byte count、filename、MIME type 和 `purpose=user_data`。添加一个或多个 Part 后，按组装顺序将 Part ID 传给 `complete`。完成后会返回包含最终 File 的 Upload。 ```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` 取消未完成的 Upload。相同 complete intent 或 cancel 可安全重试；当 complete、cancel 或 expiry 竞争且另一个终态已经胜出时，返回 `409 upload_state_conflict`。 ## CLI 与 SDK resource 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-CN/docs/resources/sdks)。 ## 生命周期行为 File content 不可变。删除 File 后，它会立即从 active list 中消失，并调度 storage cleanup。Upload complete 只按提供的顺序组装 Part；一次成功 complete 只创建一个 File。若 complete response 不确定，重试时请保持原有 Part ID 顺序。 --- ## 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": "Files 与 Uploads", "description": "创建、列出、下载和删除持久 File，或通过多个 Upload Part 组装 File。", "url": "https://runapi.ai/zh-CN/docs/resources/files", "mainEntityOfPage": "https://runapi.ai/zh-CN/docs/resources/files" } ] ```