Files - Upload

Reference

Service:: Azure AI Services

API Version:: 2024-10-21

Creates a new file entity by uploading data from a local machine. Uploaded files can, for example, be used for training or evaluating fine-tuned models.

POST {endpoint}/openai/files?api-version=2024-10-21

URI Parameters

Name	In	Required	Type	Description
file	formData	True	file	Gets or sets the file to upload into Azure OpenAI.
purpose	formData	True	Purpose	The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
endpoint	path	True	string url	Supported Cognitive Services endpoints (protocol and hostname, for example: https://aoairesource.openai.azure.com. Replace "aoairesource" with your Azure OpenAI account name).
api-version	query	True	string	The requested API version.

Request Header

Media Types: "multipart/form-data"

Name	Required	Type	Description
api-key	True	string	Provide your Cognitive Services Azure OpenAI account key here.

Responses

Name	Type	Description
201 Created	File	The file has been successfully created. Headers Location: string
Other Status Codes	ErrorResponse	An error occurred.

Name

Type

Description

201 Created

File

The file has been successfully created.

Headers

Location: string

Other Status Codes

ErrorResponse

An error occurred.

Security

api-key

Provide your Cognitive Services Azure OpenAI account key here.

Type: apiKey
In: header

Examples

Upload a file.

Sample request

HTTP

POST https://aoairesource.openai.azure.com/openai/files?api-version=2024-10-21

Sample response

Status code:: 201

location: https://aoairesource.openai.azure.com/openai/files/file-181a1cbdcdcf4677ada87f63a0928099

{
  "status": "pending",
  "purpose": "fine-tune",
  "filename": "puppy.jsonl",
  "id": "file-181a1cbdcdcf4677ada87f63a0928099",
  "created_at": 1646126127,
  "object": "file"
}

Definitions

Name	Description
Error	Error
ErrorCode	ErrorCode
ErrorResponse	ErrorResponse
File	File
FileState	FileState
InnerError	InnerError
InnerErrorCode	InnerErrorCode
Purpose	Purpose
TypeDiscriminator	TypeDiscriminator

Error

Name	Type	Description
code	ErrorCode	ErrorCode Error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
details	Error[]	The error details if available.
innererror	InnerError	InnerError Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
message	string	The message of this error.
target	string	The location where the error happened if available.

ErrorCode

Name	Type	Description
conflict	string	The requested operation conflicts with the current resource state.
contentFilter	string	Image generation failed as a result of our safety system.
fileImportFailed	string	Import of file failed.
forbidden	string	The operation is forbidden for the current user/api key.
internalFailure	string	Internal error. Please retry.
invalidPayload	string	The request data is invalid for this operation.
itemDoesAlreadyExist	string	The item does already exist.
jsonlValidationFailed	string	Validation of jsonl data failed.
notFound	string	The resource is not found.
quotaExceeded	string	Quota exceeded.
serviceUnavailable	string	The service is currently not available.
tooManyRequests	string	Too many requests. Please retry later.
unauthorized	string	The current user/api key is not authorized for the operation.
unexpectedEntityState	string	The operation cannot be executed in the current resource's state.

ErrorResponse

Name	Type	Description
error	Error	Error Error content as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

File

Name	Type	Description
bytes	integer	The size of this file when available (can be null). File sizes larger than 2^53-1 are not supported to ensure compatibility with JavaScript integers.
created_at	integer	A timestamp when this job or item was created (in unix epochs).
filename	string	The name of the file.
id	string	The identity of this item.
object	TypeDiscriminator	TypeDiscriminator Defines the type of an object.
purpose	Purpose	Purpose The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
status	FileState	FileState The state of a file.
status_details	string	The error message with details in case processing of this file failed.

FileState

Name	Type	Description
deleted	string	The entity has been deleted but may still be referenced by other entities predating the deletion. It can be categorized as a terminal state.
deleting	string	The entity is ni the process to be deleted. This state is not returned by Azure OpenAI and exposed only for compatibility. It can be categorized as an active state.
error	string	The operation has completed processing with a failure and cannot be further consumed. It can be categorized as a terminal state.
pending	string	The operation was created and is not queued to be processed in the future. It can be categorized as an inactive state.
processed	string	The operation has successfully be processed and is ready for consumption. It can be categorized as a terminal state.
running	string	The operation has started to be processed. It can be categorized as an active state.
uploaded	string	The file has been uploaded but it's not yet processed. This state is not returned by Azure OpenAI and exposed only for compatibility. It can be categorized as an inactive state.

InnerError

Name	Type	Description
code	InnerErrorCode	InnerErrorCode Inner error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
innererror	InnerError	InnerError Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

InnerErrorCode

Name	Type	Description
invalidPayload	string	The request data is invalid for this operation.

Purpose

Name	Type	Description
assistants	string	This file contains data to be used in assistants.
assistants_output	string	This file contains the results of an assistant.
batch	string	This file contains the input data for a batch.
batch_output	string	This file contains the results of a batch.
fine-tune	string	This file contains training data for a fine tune job.
fine-tune-results	string	This file contains the results of a fine tune job.

TypeDiscriminator

Name	Type	Description
batch	string	This object represents a batch.
file	string	This object represents a file.
fine_tuning.job	string	This object represents a fine tune job.
fine_tuning.job.checkpoint	string	This object represents a checkpoint of a fine tuning job.
fine_tuning.job.event	string	This object represents an event of a fine tuning job.
list	string	This object represents a list of other objects.
model	string	This object represents a model (can be a base model or fine tune job result).
upload	string	This object represents a file upload.
upload.part	string	This object represents part of a file upload.

Share via

Files - Upload

URI Parameters

Request Header

Responses

Security

api-key

Examples

Upload a file.

Sample request

Sample response

Definitions

Error

ErrorCode

ErrorResponse

File

FileState

InnerError

InnerErrorCode

Purpose

TypeDiscriminator

Additional resources