OpenAI Uploads 接口参考

Uploads（分片上传）

取消上传

post /uploads/{upload_id}/cancel

取消上传对象（Upload）。取消后不能再向其中添加分片（Part）。

返回状态为cancelled的Upload对象。

路径参数

• upload_id: string：上传对象的 ID。

返回值

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

Upload对象可以接收以分片（Part）形式提供的字节块。

• id: string

Upload对象的唯一标识符，可在API端点中引用。

• bytes: integer

计划上传的字节数。

• created_at: integer（Unix 时间戳）

Upload对象创建时的Unix时间戳，单位为秒。

• expires_at: integer（Unix 时间戳）

Upload对象过期时的Unix时间戳，单位为秒。

• filename: string

要上传的文件名称。

• purpose: string

文件的预期用途。可接受的值见此处。

• status: "pending" or "completed" or "cancelled" or "expired"

Upload对象的状态。

• "pending"

• "completed"

• "cancelled"

• "expired"

• file: optional FileObject or null

Upload完成后可使用的File对象。

• 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。

• object: optional "upload"

对象类型，固定为"upload"。

• "upload"

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads/$UPLOAD_ID/cancel \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"

响应

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

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

示例

原文示例待核：取消上传接口要求POST，但此curl片段未设置请求方法，会默认为GET；保留来源代码，请勿将其视为已验证的可运行调用。

## [中文] 发送GET请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
## [中文] 原文此示例未指定POST，curl默认GET；取消上传端点要求POST，原样保留待核。
curl https://api.openai.com/v1/uploads/upload_abc123/cancel

响应

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

{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "cancelled",
  "expires_at": 1719127296
}

完成上传

post /uploads/{upload_id}/complete

完成Upload对象的上传。

返回的Upload对象中嵌套着一个File对象，可以直接用于平台的其他功能。

通过传入有序的分片ID列表，可以指定分片的顺序。

完成上传时的字节数必须与创建Upload对象时最初指定的字节数一致。Upload完成后不能再添加分片。返回状态为completed的Upload对象，其中额外包含file属性，存放已创建且可用的File对象。

路径参数

• upload_id: string：上传对象的 ID。

请求体参数

媒体类型为 application/json。

• part_ids: array of string

按顺序排列的分片ID列表。

• md5: optional string

可选的文件内容md5校验和，用于核对上传的字节是否符合预期。

返回值

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

Upload对象可以接收以分片（Part）形式提供的字节块。

• id: string

Upload对象的唯一标识符，可在API端点中引用。

• bytes: integer

计划上传的字节数。

• created_at: integer（Unix 时间戳）

Upload对象创建时的Unix时间戳，单位为秒。

• expires_at: integer（Unix 时间戳）

Upload对象过期时的Unix时间戳，单位为秒。

• filename: string

要上传的文件名称。

• purpose: string

文件的预期用途。可接受的值见此处。

• status: "pending" or "completed" or "cancelled" or "expired"

Upload对象的状态。

• "pending"

• "completed"

• "cancelled"

• "expired"

• file: optional FileObject or null

Upload完成后可使用的File对象。

• 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。

• object: optional "upload"

对象类型，固定为"upload"。

• "upload"

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads/$UPLOAD_ID/complete \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "part_ids": [
            "string"
          ]
        }'

响应

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

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

示例

原文示例待核：此片段的curl行与后续参数行之间缺少Shell续行符；保留原状，执行前须核对完整命令。

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads/upload_abc123/complete
  -d '{
    "part_ids": ["part_def456", "part_ghi789"]
  }'

响应

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

{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "completed",
  "expires_at": 1719127296,
  "file": {
    "id": "file-xyz321",
    "object": "file",
    "bytes": 2147483648,
    "created_at": 1719186911,
    "filename": "training_examples.jsonl",
    "purpose": "fine-tune",
    "status": "processed"
  }
}

创建上传

post /uploads

创建中间Upload对象，之后可向其添加分片。目前单个Upload最多可接收总计8 GB的数据，并在创建一小时后过期。

完成Upload后，我们会创建一个包含全部已上传分片的File对象。该文件可以像普通File对象一样用于平台的其他功能。

对于某些purpose值，必须指定正确的mime_type。请查阅对应用途支持的MIME类型。

各用途应采用的文件扩展名，请参阅创建File的文档。

返回状态为pending的Upload对象。

请求体参数

媒体类型为 application/json。

• bytes: integer

正在上传的文件的字节数。

• filename: string

要上传的文件名称。

• mime_type: string

文件的MIME类型。

此值必须属于相应文件用途所支持的MIME类型。请查看assistants和vision支持的MIME类型。

• purpose: "assistants" or "batch" or "fine-tune" or "vision"

已上传文件的预期用途。

参阅文件用途文档。

• "assistants"

• "batch"

• "fine-tune"

• "vision"

• expires_after: optional object { anchor, seconds }

文件的过期策略。默认情况下，purpose=batch的文件在30天后过期，其他文件则一直保留，直到被手动删除。

• anchor: "created_at"

过期策略所依据的起算时间戳。支持的起算点为created_at。

• "created_at"

• seconds: integer（int64，范围为 3600 至 2592000 秒）

文件在起算时间之后经过多少秒过期。必须在3600秒（1小时）到2592000秒（30天）之间。

返回值

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

Upload对象可以接收以分片（Part）形式提供的字节块。

• id: string

Upload对象的唯一标识符，可在API端点中引用。

• bytes: integer

计划上传的字节数。

• created_at: integer（Unix 时间戳）

Upload对象创建时的Unix时间戳，单位为秒。

• expires_at: integer（Unix 时间戳）

Upload对象过期时的Unix时间戳，单位为秒。

• filename: string

要上传的文件名称。

• purpose: string

文件的预期用途。可接受的值见此处。

• status: "pending" or "completed" or "cancelled" or "expired"

Upload对象的状态。

• "pending"

• "completed"

• "cancelled"

• "expired"

• file: optional FileObject or null

Upload完成后可使用的File对象。

• 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。

• object: optional "upload"

对象类型，固定为"upload"。

• "upload"

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "bytes": 0,
          "filename": "filename",
          "mime_type": "mime_type",
          "purpose": "assistants"
        }'

响应

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

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

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "purpose": "fine-tune",
    "filename": "training_examples.jsonl",
    "bytes": 2147483648,
    "mime_type": "text/jsonl",
    "expires_after": {
      "anchor": "created_at",
      "seconds": 3600
    }
  }'

响应

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

{
  "id": "upload_abc123",
  "object": "upload",
  "bytes": 2147483648,
  "created_at": 1719184911,
  "filename": "training_examples.jsonl",
  "purpose": "fine-tune",
  "status": "pending",
  "expires_at": 1719127296
}

领域类型

上传对象

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

Upload对象可以接收以分片（Part）形式提供的字节块。

• id: string

Upload对象的唯一标识符，可在API端点中引用。

• bytes: integer

计划上传的字节数。

• created_at: integer（Unix 时间戳）

Upload对象创建时的Unix时间戳，单位为秒。

• expires_at: integer（Unix 时间戳）

Upload对象过期时的Unix时间戳，单位为秒。

• filename: string

要上传的文件名称。

• purpose: string

文件的预期用途。可接受的值见此处。

• status: "pending" or "completed" or "cancelled" or "expired"

Upload对象的状态。

• "pending"

• "completed"

• "cancelled"

• "expired"

• file: optional FileObject or null

Upload完成后可使用的File对象。

• 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。

• object: optional "upload"

对象类型，固定为"upload"。

• "upload"

分片

添加上传分片

post /uploads/{upload_id}/parts

向Upload对象添加分片。分片表示待上传文件中的一块字节数据。

每个分片最大64 MB；可以持续添加分片，直到达到Upload的8 GB上限。

可以并行添加多个分片。在完成Upload时，可确定分片的预期顺序。

路径参数

• upload_id: string：上传对象的 ID。

请求体参数

媒体类型为 multipart/form-data。

• data: string：此分片的字节数据。

返回值

• UploadPart object { id, created_at, object, upload_id }

上传分片表示可添加到Upload对象的一块字节数据。

• id: string

上传分片的唯一标识符，可在API端点中引用。

• created_at: integer（Unix 时间戳）

分片创建时的Unix时间戳，单位为秒。

• object: "upload.part"

对象类型，固定为upload.part。

• "upload.part"

• upload_id: string

此分片所属Upload对象的ID。

示例

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads/$UPLOAD_ID/parts \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F 'data=@/path/to/data'

响应

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

{
  "id": "id",
  "created_at": 0,
  "object": "upload.part",
  "upload_id": "upload_id"
}

示例

原文示例待核：此片段的curl行与后续参数行之间缺少Shell续行符；保留原状，执行前须核对完整命令。

## [中文] 发送POST请求；将示例API凭证、文件或上传对象标识替换为应用使用的值。
curl https://api.openai.com/v1/uploads/upload_abc123/parts
  -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..."

响应

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

{
  "id": "part_def456",
  "object": "upload.part",
  "created_at": 1719185911,
  "upload_id": "upload_abc123"
}

领域类型

上传分片

• UploadPart object { id, created_at, object, upload_id }

上传分片表示可添加到Upload对象的一块字节数据。

• id: string

上传分片的唯一标识符，可在API端点中引用。

• created_at: integer（Unix 时间戳）

分片创建时的Unix时间戳，单位为秒。

• object: "upload.part"

对象类型，固定为upload.part。

• "upload.part"

• upload_id: string

此分片所属Upload对象的ID。