Uploads
Create upload
post /uploads
Create upload
Body Parameters
-
bytes: numberThe number of bytes in the file you are uploading.
-
filename: stringThe name of the file to upload.
-
mime_type: stringThe MIME type of the file.
This must fall within the supported MIME types for your file purpose. See the supported MIME types for assistants and vision.
-
purpose: FilePurposeThe intended purpose of the uploaded file.
See the documentation on File purposes.
-
"assistants" -
"batch" -
"fine-tune" -
"vision" -
"user_data" -
"evals"
-
-
expires_after: optional object { anchor, seconds }The expiration policy for a file. By default, files with
purpose=batchexpire after 30 days and all other files are persisted until they are manually deleted.-
anchor: "created_at"Anchor timestamp after which the expiration policy applies. Supported anchors:
created_at."created_at"
-
seconds: numberThe number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
-
Returns
-
Upload object { id, bytes, created_at, 6 more }The Upload object can accept byte chunks in the form of Parts.
-
id: stringThe Upload unique identifier, which can be referenced in API endpoints.
-
bytes: numberThe intended number of bytes to be uploaded.
-
created_at: numberThe Unix timestamp (in seconds) for when the Upload was created.
-
expires_at: numberThe Unix timestamp (in seconds) for when the Upload will expire.
-
filename: stringThe name of the file to be uploaded.
-
object: "upload"The object type, which is always "upload".
"upload"
-
purpose: stringThe intended purpose of the file. Please refer here for acceptable values.
-
status: "pending" or "completed" or "cancelled" or "expired"The status of the Upload.
-
"pending" -
"completed" -
"cancelled" -
"expired"
-
-
file: optional FileObjectThe
Fileobject represents a document that has been uploaded to OpenAI.-
id: stringThe file identifier, which can be referenced in the API endpoints.
-
bytes: numberThe size of the file, in bytes.
-
created_at: numberThe Unix timestamp (in seconds) for when the file was created.
-
filename: stringThe name of the file.
-
object: "file"The object type, which is always
file."file"
-
purpose: "assistants" or "assistants_output" or "batch" or 5 moreThe intended purpose of the file. Supported values are
assistants,assistants_output,batch,batch_output,fine-tune,fine-tune-results,vision, anduser_data.-
"assistants" -
"assistants_output" -
"batch" -
"batch_output" -
"fine-tune" -
"fine-tune-results" -
"vision" -
"user_data"
-
-
status: "uploaded" or "processed" or "error"Deprecated. The current status of the file, which can be either
uploaded,processed, orerror.-
"uploaded" -
"processed" -
"error"
-
-
expires_at: optional numberThe Unix timestamp (in seconds) for when the file will expire.
-
status_details: optional stringDeprecated. For details on why a fine-tuning training file failed validation, see the
errorfield onfine_tuning.job.
-
-
Example
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"
}'
Response
{
"id": "id",
"bytes": 0,
"created_at": 0,
"expires_at": 0,
"filename": "filename",
"object": "upload",
"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"
}
}
Example
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
}
}'
Response
{
"id": "upload_abc123",
"object": "upload",
"bytes": 2147483648,
"created_at": 1719184911,
"filename": "training_examples.jsonl",
"purpose": "fine-tune",
"status": "pending",
"expires_at": 1719127296
}
Complete upload
post /uploads/{upload_id}/complete
Complete upload
Path Parameters
upload_id: string
Body Parameters
-
part_ids: array of stringThe ordered list of Part IDs.
-
md5: optional stringThe optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.
Returns
-
Upload object { id, bytes, created_at, 6 more }The Upload object can accept byte chunks in the form of Parts.
-
id: stringThe Upload unique identifier, which can be referenced in API endpoints.
-
bytes: numberThe intended number of bytes to be uploaded.
-
created_at: numberThe Unix timestamp (in seconds) for when the Upload was created.
-
expires_at: numberThe Unix timestamp (in seconds) for when the Upload will expire.
-
filename: stringThe name of the file to be uploaded.
-
object: "upload"The object type, which is always "upload".
"upload"
-
purpose: stringThe intended purpose of the file. Please refer here for acceptable values.
-
status: "pending" or "completed" or "cancelled" or "expired"The status of the Upload.
-
"pending" -
"completed" -
"cancelled" -
"expired"
-
-
file: optional FileObjectThe
Fileobject represents a document that has been uploaded to OpenAI.-
id: stringThe file identifier, which can be referenced in the API endpoints.
-
bytes: numberThe size of the file, in bytes.
-
created_at: numberThe Unix timestamp (in seconds) for when the file was created.
-
filename: stringThe name of the file.
-
object: "file"The object type, which is always
file."file"
-
purpose: "assistants" or "assistants_output" or "batch" or 5 moreThe intended purpose of the file. Supported values are
assistants,assistants_output,batch,batch_output,fine-tune,fine-tune-results,vision, anduser_data.-
"assistants" -
"assistants_output" -
"batch" -
"batch_output" -
"fine-tune" -
"fine-tune-results" -
"vision" -
"user_data"
-
-
status: "uploaded" or "processed" or "error"Deprecated. The current status of the file, which can be either
uploaded,processed, orerror.-
"uploaded" -
"processed" -
"error"
-
-
expires_at: optional numberThe Unix timestamp (in seconds) for when the file will expire.
-
status_details: optional stringDeprecated. For details on why a fine-tuning training file failed validation, see the
errorfield onfine_tuning.job.
-
-
Example
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"
]
}'
Response
{
"id": "id",
"bytes": 0,
"created_at": 0,
"expires_at": 0,
"filename": "filename",
"object": "upload",
"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"
}
}
Example
curl https://api.openai.com/v1/uploads/upload_abc123/complete
-d '{
"part_ids": ["part_def456", "part_ghi789"]
}'
Response
{
"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,
"expires_at": 1719127296,
"filename": "training_examples.jsonl",
"purpose": "fine-tune",
}
}
Cancel upload
post /uploads/{upload_id}/cancel
Cancel upload
Path Parameters
upload_id: string
Returns
-
Upload object { id, bytes, created_at, 6 more }The Upload object can accept byte chunks in the form of Parts.
-
id: stringThe Upload unique identifier, which can be referenced in API endpoints.
-
bytes: numberThe intended number of bytes to be uploaded.
-
created_at: numberThe Unix timestamp (in seconds) for when the Upload was created.
-
expires_at: numberThe Unix timestamp (in seconds) for when the Upload will expire.
-
filename: stringThe name of the file to be uploaded.
-
object: "upload"The object type, which is always "upload".
"upload"
-
purpose: stringThe intended purpose of the file. Please refer here for acceptable values.
-
status: "pending" or "completed" or "cancelled" or "expired"The status of the Upload.
-
"pending" -
"completed" -
"cancelled" -
"expired"
-
-
file: optional FileObjectThe
Fileobject represents a document that has been uploaded to OpenAI.-
id: stringThe file identifier, which can be referenced in the API endpoints.
-
bytes: numberThe size of the file, in bytes.
-
created_at: numberThe Unix timestamp (in seconds) for when the file was created.
-
filename: stringThe name of the file.
-
object: "file"The object type, which is always
file."file"
-
purpose: "assistants" or "assistants_output" or "batch" or 5 moreThe intended purpose of the file. Supported values are
assistants,assistants_output,batch,batch_output,fine-tune,fine-tune-results,vision, anduser_data.-
"assistants" -
"assistants_output" -
"batch" -
"batch_output" -
"fine-tune" -
"fine-tune-results" -
"vision" -
"user_data"
-
-
status: "uploaded" or "processed" or "error"Deprecated. The current status of the file, which can be either
uploaded,processed, orerror.-
"uploaded" -
"processed" -
"error"
-
-
expires_at: optional numberThe Unix timestamp (in seconds) for when the file will expire.
-
status_details: optional stringDeprecated. For details on why a fine-tuning training file failed validation, see the
errorfield onfine_tuning.job.
-
-
Example
curl https://api.openai.com/v1/uploads/$UPLOAD_ID/cancel \
-X POST \
-H "Authorization: Bearer $OPENAI_API_KEY"
Response
{
"id": "id",
"bytes": 0,
"created_at": 0,
"expires_at": 0,
"filename": "filename",
"object": "upload",
"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"
}
}
Example
curl https://api.openai.com/v1/uploads/upload_abc123/cancel
Response
{
"id": "upload_abc123",
"object": "upload",
"bytes": 2147483648,
"created_at": 1719184911,
"filename": "training_examples.jsonl",
"purpose": "fine-tune",
"status": "cancelled",
"expires_at": 1719127296
}
Domain Types
Upload
-
Upload object { id, bytes, created_at, 6 more }The Upload object can accept byte chunks in the form of Parts.
-
id: stringThe Upload unique identifier, which can be referenced in API endpoints.
-
bytes: numberThe intended number of bytes to be uploaded.
-
created_at: numberThe Unix timestamp (in seconds) for when the Upload was created.
-
expires_at: numberThe Unix timestamp (in seconds) for when the Upload will expire.
-
filename: stringThe name of the file to be uploaded.
-
object: "upload"The object type, which is always "upload".
"upload"
-
purpose: stringThe intended purpose of the file. Please refer here for acceptable values.
-
status: "pending" or "completed" or "cancelled" or "expired"The status of the Upload.
-
"pending" -
"completed" -
"cancelled" -
"expired"
-
-
file: optional FileObjectThe
Fileobject represents a document that has been uploaded to OpenAI.-
id: stringThe file identifier, which can be referenced in the API endpoints.
-
bytes: numberThe size of the file, in bytes.
-
created_at: numberThe Unix timestamp (in seconds) for when the file was created.
-
filename: stringThe name of the file.
-
object: "file"The object type, which is always
file."file"
-
purpose: "assistants" or "assistants_output" or "batch" or 5 moreThe intended purpose of the file. Supported values are
assistants,assistants_output,batch,batch_output,fine-tune,fine-tune-results,vision, anduser_data.-
"assistants" -
"assistants_output" -
"batch" -
"batch_output" -
"fine-tune" -
"fine-tune-results" -
"vision" -
"user_data"
-
-
status: "uploaded" or "processed" or "error"Deprecated. The current status of the file, which can be either
uploaded,processed, orerror.-
"uploaded" -
"processed" -
"error"
-
-
expires_at: optional numberThe Unix timestamp (in seconds) for when the file will expire.
-
status_details: optional stringDeprecated. For details on why a fine-tuning training file failed validation, see the
errorfield onfine_tuning.job.
-
-
Parts
Add upload part
post /uploads/{upload_id}/parts
Add upload part
Path Parameters
upload_id: string
Returns
-
UploadPart object { id, created_at, object, upload_id }The upload Part represents a chunk of bytes we can add to an Upload object.
-
id: stringThe upload Part unique identifier, which can be referenced in API endpoints.
-
created_at: numberThe Unix timestamp (in seconds) for when the Part was created.
-
object: "upload.part"The object type, which is always
upload.part."upload.part"
-
upload_id: stringThe ID of the Upload object that this Part was added to.
-
Example
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'
Response
{
"id": "id",
"created_at": 0,
"object": "upload.part",
"upload_id": "upload_id"
}
Example
curl https://api.openai.com/v1/uploads/upload_abc123/parts
-F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..."
Response
{
"id": "part_def456",
"object": "upload.part",
"created_at": 1719185911,
"upload_id": "upload_abc123"
}
Domain Types
Upload Part
-
UploadPart object { id, created_at, object, upload_id }The upload Part represents a chunk of bytes we can add to an Upload object.
-
id: stringThe upload Part unique identifier, which can be referenced in API endpoints.
-
created_at: numberThe Unix timestamp (in seconds) for when the Part was created.
-
object: "upload.part"The object type, which is always
upload.part."upload.part"
-
upload_id: stringThe ID of the Upload object that this Part was added to.
-