swagger: '2.0'
info:
title: Microsoft Azure Azure OpenAI API version 2023-05-15
description: APIs for fine-tuning and managing deployments of OpenAI models.
version: '2023-05-15'
paths:
/files:
get:
tags:
- 'Files:'
summary: "Microsoft Azure Gets A List Of All Files Owned By The Azure Openai Resource \r\nthese Include User Uploaded Content Like Files With Purpose \"fine Tune\" For Training Or Validation Of Fine Tunes Models\r\nas Well As Files That Are Generated By The Service Such As \"fine Tune Results\" Which Contains Various Metrics For The Corresponding Fine Tune Job"
operationId: microsoftAzureFilesList
produces:
- application/json
parameters:
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/FileList'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting all files owned by this account.:
$ref: ./examples/get_files.json
description: Needs a more full description created.
post:
tags:
- 'Files:'
summary: >-
Microsoft Azure 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
operationId: microsoftAzureFilesUpload
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- $ref: '#/parameters/apiVersionQueryParameter'
- in: formData
name: purpose
description: >-
The intended purpose of the uploaded documents. Use "fine-tune" for
fine-tuning. This allows us to validate the format of the uploaded
file.
required: true
type: string
enum:
- fine-tune
- fine-tune-results
x-ms-enum:
name: Purpose
modelAsString: true
values:
- value: fine-tune
description: This file contains training data for a fine tune job.
- value: fine-tune-results
description: This file contains the results of a fine tune job.
- in: formData
name: file
description: Gets or sets the file to upload into Azure OpenAI.
required: true
type: file
responses:
'201':
description: The file has been successfully created.
schema:
$ref: '#/definitions/File'
headers:
Location:
description: The location of the newly created item.
type: string
format: url
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Upload a file.:
$ref: ./examples/upload_file.json
description: Needs a more full description created.
/files/{file-id}:
get:
tags:
- 'Files:'
summary: >-
Microsoft Azure Gets Details For A Single File Specified By The Given File Id Including Status, Size, Purpose, Etc
operationId: microsoftAzureFilesGet
produces:
- application/json
parameters:
- in: path
name: file-id
description: The identifier of the file.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/File'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting a file.:
$ref: ./examples/get_file.json
description: Needs a more full description created.
delete:
tags:
- 'Files:'
summary: "Microsoft Azure Deletes The File With The Given File Id \r\ndeletion Is Also Allowed If A File Was Used, E G , As Training File In A Fine Tune Job"
operationId: microsoftAzureFilesDelete
produces:
- application/json
parameters:
- in: path
name: file-id
description: The identifier of the file.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'204':
description: The file was successfully deleted.
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Deleting a file.:
$ref: ./examples/delete_file.json
description: Needs a more full description created.
/files/{file-id}/content:
get:
tags:
- 'Files:'
summary: "Microsoft Azure Gets The Content Of The File Specified By The Given File Id \r\nfiles Can Be User Uploaded Content Or Generated By The Service Like Result Metrics Of A Fine Tune Job"
operationId: microsoftAzureFilesGetcontent
produces:
- application/octet-stream
- application/json
parameters:
- in: path
name: file-id
description: The identifier of the file.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
type: file
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting the file content.:
$ref: ./examples/get_file_content.json
description: Needs a more full description created.
/files/import:
post:
tags:
- 'Files:'
summary: >-
Microsoft Azure Creates A New File Entity By Importing Data From A Provided Url Uploaded Files Can, For Example, Be Used For Training Or Evaluating Fine Tuned Models
operationId: microsoftAzureFilesImport
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/apiVersionQueryParameter'
- in: body
name: fileImport
description: >-
The definition of the file to create including its purpose, the file
name and the url of the file location.
required: true
schema:
$ref: '#/definitions/FileImport'
responses:
'201':
description: The file has been successfully created.
schema:
$ref: '#/definitions/File'
headers:
Location:
description: The location of the newly created item.
type: string
format: url
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Importing a file with a blob url as source.:
$ref: ./examples/import_file.json
description: Needs a more full description created.
/fine-tunes:
get:
tags:
- 'Fine-Tunes:'
summary: "Microsoft Azure Gets A List Of All Fine Tune Jobs Owned By The Azure Openai Resource \r\nthe Details That Are Returned For Each Fine Tune Job Contain Besides Its Identifier\r\nthe Base Model, Training And Validation Files, Hyper Parameters, Time Stamps, Status And Events \r\nevents Are Created When The Job Status Changes, E G Running Or Complete, And When Results Are Uploaded"
operationId: microsoftAzureFinetunesList
produces:
- application/json
parameters:
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/FineTuneList'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting all fine tune jobs owned by this account.:
$ref: ./examples/get_finetunes.json
description: Needs a more full description created.
post:
tags:
- 'Fine-Tunes:'
summary: "Microsoft Azure Creates A Job That Fine Tunes A Specified Model From A Given Training File \r\nresponse Includes Details Of The Enqueued Job Including Job Status And Hyper Parameters \r\nthe Name Of The Fine Tuned Model Is Added To The Response Once Complete"
operationId: microsoftAzureFinetunesCreate
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: '#/parameters/apiVersionQueryParameter'
- in: body
name: fineTune
description: "The specification of the fine-tuned model to create.\r\nRequired parameters are the base model and the training file to use.\r\nOptionally a validation file can be specified to compute validation metrics during training.\r\nHyper parameters will be set to default values or can by optionally specified.\r\nThese include batch size, learning rate multiplier, number of epochs and others."
required: true
schema:
$ref: '#/definitions/FineTuneCreation'
responses:
'201':
description: The fine tune has been successfully created.
schema:
$ref: '#/definitions/FineTune'
headers:
Location:
description: The location of the newly created item.
type: string
format: url
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Creating a fine tune job.:
$ref: ./examples/post_finetune.json
Creating a fine tune job for classification.:
$ref: ./examples/post_classification_finetune.json
description: Needs a more full description created.
/fine-tunes/{fine-tune-id}:
get:
tags:
- 'Fine-Tunes:'
summary: "Microsoft Azure Gets Details For A Single Fine Tune Job Specified By The Given Fine Tune Id \r\nthe Details Contain The Base Model, Training And Validation Files, Hyper Parameters, Time Stamps, Status And Events \r\nevents Are Created When The Job Status Changes, E G Running Or Complete, And When Results Are Uploaded"
operationId: microsoftAzureFinetunesGet
produces:
- application/json
parameters:
- in: path
name: fine-tune-id
description: The identifier of the fine-tune job.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/FineTune'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting a fine tune job.:
$ref: ./examples/get_finetune.json
description: Needs a more full description created.
delete:
tags:
- 'Fine-Tunes:'
summary: 'Microsoft Azure Deletes The Fine Tune Job Specified By The Given Fine Tune Id'
operationId: microsoftAzureFinetunesDelete
produces:
- application/json
parameters:
- in: path
name: fine-tune-id
description: The identifier of the fine-tune job.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'204':
description: The fine tune was successfully deleted.
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Deleting a fine tune job.:
$ref: ./examples/delete_finetune.json
description: Needs a more full description created.
/fine-tunes/{fine-tune-id}/events:
get:
tags:
- 'Fine-Tunes:'
summary: "Microsoft Azure Gets The Events For The Fine Tune Job Specified By The Given Fine Tune Id \r\nevents Are Created When The Job Status Changes, E G Running Or Complete, And When Results Are Uploaded"
operationId: microsoftAzureFinetunesGetevents
produces:
- application/json
- text/event-stream
parameters:
- in: path
name: fine-tune-id
description: The identifier of the fine-tune job.
required: true
type: string
- in: query
name: stream
description: "A flag indicating whether to stream events for the fine-tune job. If set to true,\r\n events will be sent as data-only server-sent events as they become available. The stream will terminate with\r\n a data: [DONE] message when the job is finished (succeeded, cancelled, or failed).\r\n If set to false, only events generated so far will be returned.."
type: boolean
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/EventList'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting events of a fine tune job.:
$ref: ./examples/get_finetune_events.json
description: Needs a more full description created.
/fine-tunes/{fine-tune-id}/cancel:
post:
tags:
- 'Fine-Tunes:'
summary: >-
Microsoft Azure Cancels The Processing Of The Fine Tune Job Specified By The Given Fine Tune Id
operationId: microsoftAzureFinetunesCancel
produces:
- application/json
parameters:
- in: path
name: fine-tune-id
description: The identifier of the fine-tune job.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: The fine tune has been successfully canceled
schema:
$ref: '#/definitions/FineTune'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Canceling a fine tune job.:
$ref: ./examples/cancel_finetune.json
description: Needs a more full description created.
/models:
get:
tags:
- 'Models:'
summary: "Microsoft Azure Gets A List Of All Models That Are Accessible By The Azure Openai Resource \r\nthese Include Base Models As Well As All Successfully Completed Fine Tuned Models Owned By The Azure Openai Resource"
operationId: microsoftAzureModelsList
produces:
- application/json
parameters:
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ModelList'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting all models owned by account.:
$ref: ./examples/get_models.json
description: Needs a more full description created.
/models/{model-id}:
get:
tags:
- 'Models:'
summary: 'Microsoft Azure Gets Details For The Model Specified By The Given Modelid'
operationId: microsoftAzureModelsGet
produces:
- application/json
parameters:
- in: path
name: model-id
description: The identifier of the model.
required: true
type: string
- $ref: '#/parameters/apiVersionQueryParameter'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Model'
default:
description: An error occurred.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Getting a base model.:
$ref: ./examples/get_model_base.json
Getting a fine-tuned model.:
$ref: ./examples/get_model_finetune.json
description: Needs a more full description created.
definitions:
Capabilities:
title: Capabilities
description: The capabilities of a base or fine tune model.
required:
- chat_completion
- completion
- embeddings
- fine_tune
- inference
type: object
properties:
fine_tune:
description: A value indicating whether a model can be used for fine tuning.
type: boolean
inference:
description: A value indicating whether a model can be deployed.
type: boolean
completion:
description: A value indicating whether a model supports completion.
type: boolean
chat_completion:
description: A value indicating whether a model supports chat completion.
type: boolean
embeddings:
description: A value indicating whether a model supports embeddings.
type: boolean
Deprecation:
title: Deprecation
description: "Defines the dates of deprecation for the different use cases of a model.\r\nUsually base models support 1 year of fine tuning after creation. Inference is typically supported 2 years after creation of base or\r\nfine tuned models. The exact dates are specified in the properties."
required:
- inference
type: object
properties:
fine_tune:
format: unixtime
description: >-
The end date of fine tune support of this model. Will be `null` for
fine tune models.
type: integer
inference:
format: unixtime
description: The end date of inference support of this model.
type: integer
Error:
title: Error
description: "Error content as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
required:
- code
- message
type: object
properties:
code:
$ref: '#/definitions/ErrorCode'
message:
description: The message of this error.
minLength: 1
type: string
target:
description: The location where the error happened if available.
type: string
details:
description: The error details if available.
type: array
items:
$ref: '#/definitions/Error'
innererror:
$ref: '#/definitions/InnerError'
ErrorCode:
title: ErrorCode
description: "Error codes as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
enum:
- conflict
- invalidPayload
- forbidden
- notFound
- unexpectedEntityState
- itemDoesAlreadyExist
- serviceUnavailable
- internalFailure
- quotaExceeded
- jsonlValidationFailed
- fileImportFailed
type: string
x-ms-enum:
name: ErrorCode
modelAsString: true
values:
- value: conflict
description: The requested operation conflicts with the current resource state.
- value: invalidPayload
description: The request data is invalid for this operation.
- value: forbidden
description: The operation is forbidden for the current user/api key.
- value: notFound
description: The resource is not found.
- value: unexpectedEntityState
description: The operation cannot be executed in the current resource's state.
- value: itemDoesAlreadyExist
description: The item does already exist.
- value: serviceUnavailable
description: The service is currently not available.
- value: internalFailure
description: Internal error. Please retry.
- value: quotaExceeded
description: Quota exceeded.
- value: jsonlValidationFailed
description: Validation of jsonl data failed.
- value: fileImportFailed
description: Import of file failed.
ErrorResponse:
title: ErrorResponse
description: "Error response as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
required:
- error
type: object
properties:
error:
$ref: '#/definitions/Error'
Event:
title: Event
required:
- created_at
- level
- message
type: object
properties:
object:
$ref: '#/definitions/TypeDiscriminator'
created_at:
format: unixtime
description: A timestamp when this event was created (in unix epochs).
type: integer
level:
$ref: '#/definitions/LogLevel'
message:
description: >-
The message describing the event. This can be a change of state, e.g.,
enqueued, started, failed or completed, or other events like uploaded
results.
minLength: 1
type: string
EventList:
title: EventList
description: Represents a list of events.
type: object
properties:
object:
$ref: '#/definitions/TypeDiscriminator'
data:
description: The list of items.
type: array
items:
$ref: '#/definitions/Event'
File:
title: File
description: >-
A file is a document usable for training and validation. It can also be a
service generated document with result details.
required:
- filename
- purpose
type: object
properties:
object:
$ref: '#/definitions/TypeDiscriminator'
status:
$ref: '#/definitions/State'
created_at:
format: unixtime
description: A timestamp when this job or item was created (in unix epochs).
type: integer
readOnly: true
updated_at:
format: unixtime
description: A timestamp when this job or item was modified last (in unix epochs).
type: integer
readOnly: true
id:
description: The identity of this item.
type: string
readOnly: true
bytes:
format: int64
description: "The size of this file when available (can be null). File sizes larger than 2^53-1 are not supported to ensure compatibility\r\nwith JavaScript integers."
type: integer
readOnly: true
purpose:
$ref: '#/definitions/Purpose'
filename:
description: The name of the file.
minLength: 1
type: string
statistics:
$ref: '#/definitions/FileStatistics'
error:
$ref: '#/definitions/Error'
FileImport:
title: FileImport
description: >-
Defines a document to import from an external content url to be usable
with Azure OpenAI.
required:
- content_url
- filename
- purpose
type: object
properties:
purpose:
$ref: '#/definitions/Purpose'
filename:
description: "The name of the [JSON Lines](https://jsonlines.readthedocs.io/en/latest/) file to be uploaded.\r\nIf the `purpose` is set to \"fine-tune\", each line is a JSON record with \"prompt\" and \"completion\" fields representing your training examples."
minLength: 1
type: string
content_url:
format: url
description: >-
The url to download the document from (can be SAS url of a blob or any
other external url accessible with a GET request).
type: string
FileList:
title: FileList
description: Represents a list of files.
type: object
properties:
object:
$ref: '#/definitions/TypeDiscriminator'
data:
description: The list of items.
type: array
items:
$ref: '#/definitions/File'
FileStatistics:
title: FileStatistics
description: >-
A file is a document usable for training and validation. It can also be a
service generated document with result details.
type: object
properties:
tokens:
format: int32
description: >-
The number of tokens used in prompts and completions for files of kind
"fine-tune" once validation of file content is complete.
type: integer
examples:
format: int32
description: >-
The number of contained training examples in files of kind "fine-tune"
once validation of file content is complete.
type: integer
FineTune:
title: FineTune
description: Fine tuning is a job to tailor a model to specific training data.
required:
- model
- training_files
type: object
properties:
object:
$ref: '#/definitions/TypeDiscriminator'
status:
$ref: '#/definitions/State'
created_at:
format: unixtime
description: A timestamp when this job or item was created (in unix epochs).
type: integer
readOnly: true
updated_at:
format: unixtime
description: A timestamp when this job or item was modified last (in unix epochs).
type: integer
readOnly: true
id:
description: The identity of this item.
type: string
readOnly: true
model:
description: The identifier (model-id) of the base model used for the fine-tune.
minLength: 1
type: string
fine_tuned_model:
description: "The identifier (model-id) of the resulting fine tuned model. This property is only populated for successfully completed fine-tune runs.\r\nUse this identifier to create a deployment for inferencing."
type: string
training_files:
description: >-
The file identities (file-id) that are used for training the fine
tuned model.
type: array
items:
$ref: '#/definitions/File'
validation_files:
description: >-
The file identities (file-id) that are used to evaluate the fine tuned
model during training.
type: array
items:
$ref: '#/definitions/File'
result_files:
description: "The result file identities (file-id) containing training and evaluation metrics in csv format.\r\nThe file is only available for successfully completed fine-tune runs."
type: array
items:
$ref: '#/definitions/File'
events:
description: >-
The events that show the progress of the fine-tune run including
queued, running and completed.
type: array
items:
$ref: '#/definitions/Event'
organisation_id:
description: >-
The organisation id of this fine tune job. Unused on Azure OpenAI;
compatibility for OpenAI only.
type: string
user_id:
description: >-
The user id of this fine tune job. Unused on Azure OpenAI;
compatibility for OpenAI only.
type: string
hyperparams:
$ref: '#/definitions/HyperParameters'
suffix:
description: The suffix used to identify the fine-tuned model.
type: string
error:
$ref: '#/definitions/Error'
FineTuneCreation:
title: FineTuneCreation
description: Defines the values of a fine tune job.
required:
- model
- training_file
type: object
properties:
model:
description: The identifier (model-id) of the base model used for this fine-tune.
minLength: 1
type: string
training_file:
description: >-
The file identity (file-id) that is used for training this fine tuned
model.
minLength: 1
type: string
validation_file:
description: >-
The file identity (file-id) that is used to evaluate the fine tuned
model during training.
type: string
suffix:
description: >-
The suffix used to identify the fine-tuned model. The suffix can
contain up to 40 characters (a-z, A-Z, 0-9,- and _) that will be added
to your fine-tuned model name.
type: string
n_epochs:
format: int32
description: >-
The number of epochs to train the model for. An epoch refers to one
full cycle through the training dataset.
type: integer
batch_size:
format: int32
description: "The batch size to use for training. The batch size is the number of training examples used to train a single forward and backward pass.\r\nIn general, we've found that larger batch sizes tend to work better for larger datasets.\r\nThe default value as well as the maximum value for this property are specific to a base model."
type: integer
learning_rate_multiplier:
format: double
description: "The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning rate used for pre-training multiplied by this value.\r\nLarger learning rates tend to perform better with larger batch sizes.\r\nWe recommend experimenting with values in the range 0.02 to 0.2 to see what produces the best results."
type: number
prompt_loss_weight:
format: double
description: "The weight to use for loss on the prompt tokens. This controls how much the model tries to learn to generate the prompt\r\n(as compared to the completion which always has a weight of 1.0), and can add a stabilizing effect to training when completions are short.\r\nIf prompts are extremely long (relative to completions), it may make sense to reduce this weight so as to avoid over-prioritizing learning the prompt."
type: number
compute_classification_metrics:
description: "A value indicating whether to compute classification metrics.\r\nIf set, we calculate classification-specific metrics such as accuracy and F-1 score using the validation set at the end of every epoch.\r\nThese metrics can be viewed in the results file. In order to compute classification metrics, you must provide a validation_file.Additionally,\r\nyou must specify classification_n_classes for multiclass classification or classification_positive_class for binary classification."
type: boolean
classification_n_classes:
format: int32
description: "The number of classes in a classification task.\r\nThis parameter is required for multiclass classification."
type: integer
classification_positive_class:
description: "The positive class in binary classification.\r\nThis parameter is needed to generate precision, recall, and F1 metrics when doing binary classification."
type: string
classification_betas:
description: "The classification beta values. If this is provided, we calculate F-beta scores at the specified beta values.\r\nThe F-beta score is a generalization of F-1 score. This is only used for binary classification.\r\nWith a beta of 1 (i.e.the F-1 score), precision and recall are given the same weight.\r\nA larger beta score puts more weight on recall and less on precision. A smaller beta score puts more weight on precision and less on recall."
type: array
items:
format: double
type: number
FineTuneList:
title: FineTuneList
description: Represents a list of fine tunes.
type: object
properties:
object:
$ref: '#/definitions/TypeDiscriminator'
data:
description: The list of items.
type: array
items:
$ref: '#/definitions/FineTune'
HyperParameters:
title: HyperParameters
description: The hyper parameter settings used in a fine tune job.
type: object
properties:
batch_size:
format: int32
description: "The batch size to use for training. The batch size is the number of training examples used to train a single forward and backward pass.\r\nIn general, we've found that larger batch sizes tend to work better for larger datasets.\r\nThe default value as well as the maximum value for this property are specific to a base model."
type: integer
learning_rate_multiplier:
format: double
description: "The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning rate used for pre-training multiplied by this value.\r\nLarger le
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/azure-openai-api-version-2023-05-15-openapi-original.yml