OpenAI API Files 接口参考
Files 文件资源
获取文件内容
get /files/{file_id}/content
返回包含指定文件内容的响应。
路径参数
file_id: string
此请求使用的文件 ID。
返回值
file
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files/$FILE_ID/content \
-H "Authorization: Bearer $OPENAI_API_KEY"
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files/file-abc123/content \
-H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl
上传文件
post /files
上传可供多个接口使用的文件。单个文件 最大为 512 MB,每个项目的文件存储总量 最大为 2.5 TB。组织级别不设总存储上限。此上传 接口按每位已认证用户限速,每分钟最多 1,000 次请求。
- Assistants API 支持最多 200 万词元且符合特定 文件类型的文件。详情参阅 Assistants 工具指南 中的说明。
- 微调 API 仅支持
.jsonl文件。用于微调 的输入还须符合相应格式要求,分别用于 聊天模型或 补全模型。 - Batch API 仅支持不超过 200 MB 的
.jsonl文件。输入 还必须符合规定的 格式。 - 用于检索或
file_search数据摄取时,先在这里上传文件。如 需将多个已上传文件关联到同一个向量存储,请使用/vector_stores/{vector_store_id}/file_batches批量关联,无需逐个关联。向量存储关联操作有单独的 限制,区别于文件上传限制,其中每个组织每分钟 最多关联 2,000 个文件。
如需提高上述存储限制,请联系支持 申请。
请求体参数
内容类型为 multipart/form-data。
file: string
要上传的文件对象,须提供文件内容。
purpose: "assistants" or "batch" or "fine-tune" or 3 more
上传文件的预期用途,可选值如下。
assistants: Used in the Assistants APIbatch: Used in the Batch APIfine-tune: Used for fine-tuningvision: Images used for vision fine-tuninguser_data: Flexible file type for any purposeevals: Used for eval data sets
"assistants"
"batch"
"fine-tune"
"vision"
"user_data"
"evals"
expires_after: optional object { anchor, seconds }
文件的过期策略。默认情况下,purpose=batch 的文件在 30 天后过期,其他文件持久保存,直到手动删除。
anchor: "created_at"
计算过期时间的基准时间戳,支持 created_at。
"created_at"
seconds: integer
文件在基准时间之后的有效秒数,范围为 3600 秒(1 小时)至 2592000 秒(30 天)。
format: int64, minimum: 3600, maximum: 2592000
返回值
FileObject object { id, bytes, created_at, 6 more }
File 对象表示已上传到 OpenAI 的文档。
id: string
文件标识,可在其他 API 接口中引用。
bytes: integer or null
文件大小,单位为字节。在已完成的文件上传响应中, 若暂时无法获取大小,此字段可为 null。
created_at: integer
文件创建时的 Unix 时间戳,单位为秒。
format: unixtime
filename: string
文件名。
object: "file"
对象类型,固定为 file。
"file"
purpose: "assistants" or "assistants_output" or "batch" or 5 more
文件的预期用途,支持 assistants、assistants_output、batch、batch_output、fine-tune、fine-tune-results、vision 和 user_data。
"assistants"
"assistants_output"
"batch"
"batch_output"
"fine-tune"
"fine-tune-results"
"vision"
"user_data"
status: "uploaded" or "processed" or "error"
此字段已弃用。文件当前状态可能为 uploaded、processed 或 error。
"uploaded"
"processed"
"error"
expires_at: optional integer
文件过期时的 Unix 时间戳,单位为秒。在已完成的 文件上传响应中,未设置过期时间时此字段可为 null。
format: unixtime
status_details: optional string
此字段已弃用。微调训练文件验证失败的原因应查看 fine_tuning.job 的 error 字段。已完成的文件上传响应在未设置详情时可返回 null。
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files \
-H 'Content-Type: multipart/form-data' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'file=@/path/to/file' \
-F purpose=assistants
200 响应示例
{
"id": "id",
"bytes": 0,
"created_at": 0,
"filename": "filename",
"object": "file",
"purpose": "assistants",
"status": "uploaded",
"expires_at": 0,
"status_details": "status_details"
}
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F purpose="fine-tune" \
-F file="@mydata.jsonl" \
-F 'expires_after[anchor]=created_at' \
-F 'expires_after[seconds]=2592000'
响应示例
{
"id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"expires_at": 1680202602,
"filename": "mydata.jsonl",
"purpose": "fine-tune",
"status": "processed"
}
删除文件
delete /files/{file_id}
删除文件,并从所有向量存储中移除此文件。
路径参数
file_id: string
此请求使用的文件 ID。
返回值
FileDeleted object { id, deleted, object }
id: string
deleted: boolean
object: "file"
"file"
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files/$FILE_ID \
-X DELETE \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
{
"id": "id",
"deleted": true,
"object": "file"
}
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files/file-abc123 \
-X DELETE \
-H "Authorization: Bearer $OPENAI_API_KEY"
响应示例
{
"id": "file-abc123",
"object": "file",
"deleted": true
}
列出文件
get /files
返回文件列表。
查询参数
after: optional string
分页游标。after 使用对象 ID 表示当前列表位置。例如,本次返回 100 个对象,最后一个 ID 为 obj_foo,则下一次请求可传入 after=obj_foo 获取下一页。
limit: optional integer (default: 10000)
返回对象数量上限,范围为 1–10,000,默认为 10,000。
order: optional "asc" or "desc" (default: "desc")
按对象的 created_at 时间戳排序,asc 为升序,desc 为降序。
"asc"
"desc"
purpose: optional string
仅返回指定用途的文件。
返回值
data: array of FileObject
id: string
文件标识,可在其他 API 接口中引用。
bytes: integer or null
文件大小,单位为字节。在已完成的文件上传响应中, 若暂时无法获取大小,此字段可为 null。
created_at: integer
文件创建时的 Unix 时间戳,单位为秒。
format: unixtime
filename: string
文件名。
object: "file"
对象类型,固定为 file。
"file"
purpose: "assistants" or "assistants_output" or "batch" or 5 more
文件的预期用途,支持 assistants、assistants_output、batch、batch_output、fine-tune、fine-tune-results、vision 和 user_data。
"assistants"
"assistants_output"
"batch"
"batch_output"
"fine-tune"
"fine-tune-results"
"vision"
"user_data"
status: "uploaded" or "processed" or "error"
此字段已弃用。文件当前状态可能为 uploaded、processed 或 error。
"uploaded"
"processed"
"error"
expires_at: optional integer
文件过期时的 Unix 时间戳,单位为秒。在已完成的 文件上传响应中,未设置过期时间时此字段可为 null。
format: unixtime
status_details: optional string
此字段已弃用。微调训练文件验证失败的原因应查看 fine_tuning.job 的 error 字段。已完成的文件上传响应在未设置详情时可返回 null。
first_id: string
has_more: boolean
last_id: string
object: string
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
{
"data": [
{
"id": "id",
"bytes": 0,
"created_at": 0,
"filename": "filename",
"object": "file",
"purpose": "assistants",
"status": "uploaded",
"expires_at": 0,
"status_details": "status_details"
}
],
"first_id": "file-abc123",
"has_more": false,
"last_id": "file-abc456",
"object": "list"
}
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY"
响应示例
{
"object": "list",
"data": [
{
"id": "file-abc123",
"object": "file",
"bytes": 175,
"created_at": 1613677385,
"expires_at": 1677614202,
"filename": "salesOverview.pdf",
"purpose": "assistants",
"status": "processed"
},
{
"id": "file-abc456",
"object": "file",
"bytes": 140,
"created_at": 1613779121,
"expires_at": 1677614202,
"filename": "puppy.jsonl",
"purpose": "fine-tune",
"status": "processed"
}
],
"first_id": "file-abc123",
"last_id": "file-abc456",
"has_more": false
}
获取文件
get /files/{file_id}
返回指定文件的信息。
路径参数
file_id: string
此请求使用的文件 ID。
返回值
FileObject object { id, bytes, created_at, 6 more }
File 对象表示已上传到 OpenAI 的文档。
id: string
文件标识,可在其他 API 接口中引用。
bytes: integer or null
文件大小,单位为字节。在已完成的文件上传响应中, 若暂时无法获取大小,此字段可为 null。
created_at: integer
文件创建时的 Unix 时间戳,单位为秒。
format: unixtime
filename: string
文件名。
object: "file"
对象类型,固定为 file。
"file"
purpose: "assistants" or "assistants_output" or "batch" or 5 more
文件的预期用途,支持 assistants、assistants_output、batch、batch_output、fine-tune、fine-tune-results、vision 和 user_data。
"assistants"
"assistants_output"
"batch"
"batch_output"
"fine-tune"
"fine-tune-results"
"vision"
"user_data"
status: "uploaded" or "processed" or "error"
此字段已弃用。文件当前状态可能为 uploaded、processed 或 error。
"uploaded"
"processed"
"error"
expires_at: optional integer
文件过期时的 Unix 时间戳,单位为秒。在已完成的 文件上传响应中,未设置过期时间时此字段可为 null。
format: unixtime
status_details: optional string
此字段已弃用。微调训练文件验证失败的原因应查看 fine_tuning.job 的 error 字段。已完成的文件上传响应在未设置详情时可返回 null。
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files/$FILE_ID \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
{
"id": "id",
"bytes": 0,
"created_at": 0,
"filename": "filename",
"object": "file",
"purpose": "assistants",
"status": "uploaded",
"expires_at": 0,
"status_details": "status_details"
}
示例
## 设置 OPENAI_API_KEY,并替换请求中的文件或聊天补全 ID。
curl https://api.openai.com/v1/files/file-abc123 \
-H "Authorization: Bearer $OPENAI_API_KEY"
响应示例
{
"id": "file-abc123",
"object": "file",
"bytes": 120000,
"created_at": 1677610602,
"expires_at": 1680202602,
"filename": "mydata.jsonl",
"purpose": "fine-tune",
"status": "processed"
}
资源类型
文件内容
FileContent = string
文件删除结果
FileDeleted object { id, deleted, object }
id: string
deleted: boolean
object: "file"
"file"
文件对象
FileObject object { id, bytes, created_at, 6 more }
File 对象表示已上传到 OpenAI 的文档。
id: string
文件标识,可在其他 API 接口中引用。
bytes: integer or null
文件大小,单位为字节。在已完成的文件上传响应中, 若暂时无法获取大小,此字段可为 null。
created_at: integer
文件创建时的 Unix 时间戳,单位为秒。
format: unixtime
filename: string
文件名。
object: "file"
对象类型,固定为 file。
"file"
purpose: "assistants" or "assistants_output" or "batch" or 5 more
文件的预期用途,支持 assistants、assistants_output、batch、batch_output、fine-tune、fine-tune-results、vision 和 user_data。
"assistants"
"assistants_output"
"batch"
"batch_output"
"fine-tune"
"fine-tune-results"
"vision"
"user_data"
status: "uploaded" or "processed" or "error"
此字段已弃用。文件当前状态可能为 uploaded、processed 或 error。
"uploaded"
"processed"
"error"
expires_at: optional integer
文件过期时的 Unix 时间戳,单位为秒。在已完成的 文件上传响应中,未设置过期时间时此字段可为 null。
format: unixtime
status_details: optional string
此字段已弃用。微调训练文件验证失败的原因应查看 fine_tuning.job 的 error 字段。已完成的文件上传响应在未设置详情时可返回 null。