codecamp

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 API
  • batch: Used in the Batch API
  • fine-tune: Used for fine-tuning
  • vision: Images used for vision fine-tuning
  • user_data: Flexible file type for any purpose
  • evals: 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。

OpenAI API Audio 接口参考
OpenAI API Moderations 接口参考
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }