OpenAI 上传文件接口

上传文件

post /files

上传可用于多个端点的文件。单个文件最大512 MB，每个项目最多可存储总计2.5 TB的文件；没有组织级总存储上限。此端点按每位已认证用户每分钟1000次请求进行速率限制。

• Assistants API支持不超过200万词元、且属于指定类型的文件，详见Assistants工具指南。
• Fine-tuning API仅支持.jsonl文件。针对聊天或补全模型进行微调时，输入还必须符合相应格式。
• Batch API仅支持最大200 MB的.jsonl文件，输入也必须符合指定格式。
• 为检索或file_search摄取数据时，应先在此上传文件。若要将多个已上传文件附加到同一个向量存储，请使用/vector_stores/{vector_store_id}/file_batches，不要逐个附加。向量存储附加操作的限制独立于文件上传，其中包括每个组织每分钟附加2000个文件的限制。

若需提高这些存储限额，请联系我们。

请求体参数

媒体类型为 multipart/form-data。

• file: string：要上传的文件对象，需提供文件内容。
• purpose：用途可选 assistants（Assistants API）、batch（Batch API）、fine-tune（微调）、vision（用于视觉微调的图像）、user_data（通用用户数据）或 evals（评测数据集）。
• expires_after：可选的文件过期策略。默认情况下，batch 文件在 30 天后过期，其余文件保留至手动删除。
  • anchor: "created_at"：以创建时间为起点。
  • seconds: integer：起点之后的有效秒数，类型为 int64，范围为 3600 至 2592000 秒。

返回值

• FileObject object { id, bytes, created_at, 6 more }

File对象表示已上传到OpenAI的文档。

• id: string

文件标识符，可在API端点中引用。

• bytes: integer or null

文件大小，单位为字节。在已完成文件上传的响应中，如果文件大小尚不可用，此值可以为null。

• created_at: integer（Unix 时间戳）

文件创建时的Unix时间戳，单位为秒。

• 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 时间戳）

文件过期时的Unix时间戳，单位为秒。在已完成文件上传的响应中，如果未设置过期时间，此值可以为null。

• status_details: optional string

已弃用。有关微调训练文件未通过验证的原因，请查看fine_tuning.job的error字段。已完成文件上传的响应在未设置这些详情时可以返回null。

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
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

响应

中文说明：以下为原文配置、命令或事件示例，字段名、枚举、标识符及数值保留。

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
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"
}