# 文件 API (/docs/api/native/file)



## 基础地址 [#基础地址]

<ApiBaseDomain prefix="/file/v1" />

## 接入 [#接入]

<QuickstartTabs snippets="{&#x22;curl&#x22;:&#x22;curl https://api-origin.invalid/file/v1/files \\\n  -H \&#x22;Authorization: Bearer $PRAXIS_API_KEY\&#x22; \\\n  -F \&#x22;purpose=user_data\&#x22; \\\n  -F \&#x22;file=@pixel.png\&#x22;&#x22;,&#x22;python&#x22;:&#x22;import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(\n    base_url=\&#x22;https://api-origin.invalid/file/v1\&#x22;,\n    api_key=os.environ[\&#x22;PRAXIS_API_KEY\&#x22;],\n)\n\nfile = client.files.create(\n    file=open(\&#x22;pixel.png\&#x22;, \&#x22;rb\&#x22;),\n    purpose=\&#x22;user_data\&#x22;,\n)&#x22;,&#x22;typescript&#x22;:&#x22;import OpenAI from \&#x22;openai\&#x22;;\nimport fs from \&#x22;node:fs\&#x22;;\n\nconst client = new OpenAI({\n  baseURL: \&#x22;https://api-origin.invalid/file/v1\&#x22;,\n  apiKey: process.env.PRAXIS_API_KEY,\n});\n\nconst file = await client.files.create({\n  file: fs.createReadStream(\&#x22;pixel.png\&#x22;),\n  purpose: \&#x22;user_data\&#x22;,\n});&#x22;}" />

单文件上限 100 MB（104857600 字节），上传与下载全程流式。不提供 Uploads 分片。文件按内容识别类型；支持格式见上传端点。组织之间的文件互不可见。

## 端点 [#端点]

| 方法     | 路径                                                                         | 说明   | 支持     |
| ------ | -------------------------------------------------------------------------- | ---- | ------ |
| POST   | [`/v1/files`](/docs/api/native/file/createFile)                            | 上传文件 | ◐ 部分支持 |
| GET    | [`/v1/files`](/docs/api/native/file/listFiles)                             | 列出文件 | ● 支持   |
| GET    | [`/v1/files/{file_id}`](/docs/api/native/file/retrieveFile)                | 查看文件 | ● 支持   |
| GET    | [`/v1/files/{file_id}/content`](/docs/api/native/file/retrieveFileContent) | 下载文件 | ● 支持   |
| DELETE | [`/v1/files/{file_id}`](/docs/api/native/file/deleteFile)                  | 删除文件 | ● 支持   |

## 与官方的差异 [#与官方的差异]

* 沿用 OpenAI 的文件和分页形状，增加 mime\_type、downloadable，以及 before 查询游标。仅自有面支持请求体 praxis.expires\_in\_seconds（3600–7776000 秒），不可与 expires\_after 同时使用；multipart 编码为 praxis\[expires\_in\_seconds]。
* <a href="/docs/api/native/file/createFile">上传文件</a>：支持 PDF、DOCX / XLSX / PPTX、PNG / JPEG / GIF / WebP、MP3 / WAV / FLAC / OGG / M4A、MP4 / WebM，以及 UTF-8 JSON / NDJSON / CSV / Markdown / 纯文本。purpose 支持 user\_data / assistants / vision。上限 104857600 字节；空文件、类型不支持、用途不支持、超限均返回 400。不提供 Uploads 分片。可用 expires\_after\[anchor] 与 expires\_after\[seconds] 或 praxis\[expires\_in\_seconds] 设置有效期，两组互斥。

参数与字段的权威定义以 [OpenAI 官方文档](https://platform.openai.com/docs/api-reference)为准。

错误按 OpenAI 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。