文件 API

2026-10-20

文件 API

（待译）

File stores uploads for conversations and knowledge bases, with metadata, downloads and deletion. Concepts and behavior follow OpenAI Files (multipart uploads, purposes and file IDs), so OpenAI Files experience applies. Differences: uploads are limited to 104857600 bytes; only user_data, assistants and vision purposes are accepted, and conversation images require user_data; praxis[expires_in_seconds] allows expiry up to 90 days, while expires_after allows up to 30 days. Start with praxis.file.files.create to upload bytes and obtain a reusable file ID.

基础地址

加载中…

接入

加载中…

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

端点

方法路径说明支持
POST/v1/files上传文件◐ 部分支持
GET/v1/files列出文件● 支持
GET/v1/files/{file_id}查看文件● 支持
GET/v1/files/{file_id}/content下载文件● 支持
DELETE/v1/files/{file_id}删除文件● 支持

与官方的差异

  • 沿用 OpenAI 的文件和分页形状，增加 mime_type、downloadable，以及 before 查询游标。仅自有面支持请求体 praxis.expires_in_seconds（3600–7776000 秒），不可与 expires_after 同时使用；multipart 编码为 praxis[expires_in_seconds]。
  • 上传文件：支持 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 官方文档为准。

错误按 OpenAI 格式返回，参见错误；额度与响应头参见限流。

POST /file/v1/files◐ 部分支持

OpenAI 官方文档 ↗

请求体

  • filestring必填

    File bytes in one multipart file part, not a filename or file ID. The file must be nonempty and at most 104857600 bytes; its content determines the MIME type.

  • purposestring必填

    Purpose label stored with the file: user_data, assistants or vision. The vision purpose accepts only PNG, JPEG, GIF and WebP images. Conversation image references require user_data.

    取值 user_dataassistantsvision
  • expires_afterobject可选

    Optional expiry relative to created_at. Files without an expiry persist until deleted.

    ▸ 展开子字段（2）
    • anchorstring必填

      Creation timestamp from which expiry is measured. Send created_at as the multipart field expires_after[anchor].

      取值 created_at
    • secondsinteger必填

      Lifetime in seconds after creation, from 3600 through 2592000. Send as expires_after[seconds]; do not combine with praxis[expires_in_seconds].

  • praxisobject可选

    Own-face extensions. Use at most one expiry setting.

    ▸ 展开子字段（1）
    • expires_in_secondsinteger可选

      Lifetime in seconds after creation, from 3600 through 7776000. Send as the multipart field praxis[expires_in_seconds]; mutually exclusive with expires_after.

返回

200 file

支持 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 格式返回，参见 错误码

响应

HTTP 200

OK

application/json

名称类型说明
idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
bytesintegerThe size of the file, in bytes.
created_atintegerThe Unix timestamp (in seconds) for when the file was created.
expires_atintegerThe Unix timestamp (in seconds) for when the file will expire.
filenamestringThe name of the file.
objectstringThe object type, which is always `file`.
purposestringUpload purpose. Image references in conversations require user_data.
statusstringDeprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
status_detailsstring | nullDeprecated; always null or absent.
mime_typestringContent-detected MIME type.
downloadablebooleanTenant-owned live files can be downloaded through this face.
scopeobjectPresent for session output files.
scope.typestringKind of scope; always `session`.
scope.idstringId of the session the file belongs to.
relative_pathstringPath within the session output directory; present for session outputs.
revisionintegerSession output revision; present for session outputs.

列出文件

GET /file/v1/files● 支持

请求参数

  • purposestring可选

    query: Only return files with the given purpose.

  • limitinteger可选
    默认 10000

    query: A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

  • orderstring可选
    默认 "desc"

    query: Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

    取值 ascdesc
  • afterstring可选

    query: File ID cursor for the next page; mutually exclusive with before. Use an ID from the current listing.

  • scope_idstring可选

    query: Session whose output files to list. Accepts sesn_ or ags_ followed by 1 to 251 letters, digits, underscores or hyphens. An existing session with no outputs returns an empty list; a nonexistent or inaccessible session returns 404.

  • beforestring可选

    query: File ID cursor for the preceding page; mutually exclusive with after. Use an ID from the current listing.

返回

200 list

错误按 OpenAI 格式返回，参见 错误码

响应

HTTP 200

OK

application/json

名称类型说明
objectstringObject type; always `list`.
dataarray<object>Files of the page, in the requested order.
data[].idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
data[].bytesintegerThe size of the file, in bytes.
data[].created_atintegerThe Unix timestamp (in seconds) for when the file was created.
data[].expires_atintegerThe Unix timestamp (in seconds) for when the file will expire.
data[].filenamestringThe name of the file.
data[].objectstringThe object type, which is always `file`.
data[].purposestringUpload purpose. Image references in conversations require user_data.
data[].statusstringDeprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
data[].status_detailsstring | nullDeprecated; always null or absent.
data[].mime_typestringContent-detected MIME type.
data[].downloadablebooleanTenant-owned live files can be downloaded through this face.
data[].scopeobjectPresent for session output files.
data[].relative_pathstringPath within the session output directory; present for session outputs.
data[].revisionintegerSession output revision; present for session outputs.
first_idstringId of the first file of the page; usable as `before` to read the preceding page.
last_idstringId of the last file of the page; usable as `after` to read the next page.
has_morebooleanWhether more files exist beyond this page.

查看文件

先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。

GET /file/v1/files/{file_id}● 支持

请求参数

  • file_idstring必填

    path: ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.

返回

200 file

错误按 OpenAI 格式返回，参见 错误码

响应

HTTP 200

OK

application/json

名称类型说明
idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
bytesintegerThe size of the file, in bytes.
created_atintegerThe Unix timestamp (in seconds) for when the file was created.
expires_atintegerThe Unix timestamp (in seconds) for when the file will expire.
filenamestringThe name of the file.
objectstringThe object type, which is always `file`.
purposestringUpload purpose. Image references in conversations require user_data.
statusstringDeprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
status_detailsstring | nullDeprecated; always null or absent.
mime_typestringContent-detected MIME type.
downloadablebooleanTenant-owned live files can be downloaded through this face.
scopeobjectPresent for session output files.
scope.typestringKind of scope; always `session`.
scope.idstringId of the session the file belongs to.
relative_pathstringPath within the session output directory; present for session outputs.
revisionintegerSession output revision; present for session outputs.

下载文件

先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。

GET /file/v1/files/{file_id}/content● 支持

请求参数

  • file_idstring必填

    path: ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.

返回

200

错误按 OpenAI 格式返回，参见 错误码

响应

HTTP 200

OK

application/octet-stream

名称类型说明
$string (binary)

删除文件

先调用「上传文件」，用返回的文件 ID 替换示例文件 ID。

DELETE /file/v1/files/{file_id}● 支持

请求参数

  • file_idstring必填

    path: ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.

返回

200 file

错误按 OpenAI 格式返回，参见 错误码

响应

HTTP 200

OK

application/json

名称类型说明
idstringFile identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
objectstringObject type; always `file`.
deletedbooleanAlways true; the file can no longer be read, though downloads already authorized may finish.