Azure OpenAI Service Batch: API

openapi: 3.2.0
info:
  title: 'Azure OpenAI API version 2024-10-21 Batch: API'
  description: APIs for fine-tuning and managing deployments of OpenAI models.
  version: '2024-10-21'
security:
- api-key: []
tags:
- name: 'Batch:'
paths:
  /batches:
    get:
      tags:
      - 'Batch:'
      summary: Gets a list of all batches owned by the Azure OpenAI resource
      operationId: Batch_List
      parameters:
      - in: query
        name: after
        description: Identifier for the last event from the previous pagination request.
        schema:
          type: string
      - in: query
        name: limit
        description: Number of batches to retrieve. Defaults to 20.
        schema:
          type: integer
          format: int32
          default: 20
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchesList'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - 'Batch:'
      summary: Creates and executes a batch from an uploaded file of requests.
      operationId: Batch_Create
      parameters:
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: The batch has been successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateRequest'
        description: The specification of the batch to create and execute.
        required: true
  /batches/{batch-id}:
    get:
      tags:
      - 'Batch:'
      summary: Gets details for a single batch specified by the given batch-id
      operationId: Batch_Get
      parameters:
      - in: path
        name: batch-id
        description: The identifier of the batch.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /batches/{batch-id}/cancel:
    post:
      tags:
      - 'Batch:'
      summary: Cancels the processing of the batch specified by the given batch-id
      operationId: Batch_Cancel
      parameters:
      - in: path
        name: batch-id
        description: The identifier of the batch.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: The batch has been successfully canceled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Batch:
      title: Batch
      description: Defines the values of a batch.
      required:
      - id
      - input_file_id
      type: object
      properties:
        id:
          description: The identity of this item.
          type: string
        object:
          $ref: '#/components/schemas/TypeDiscriminator'
        endpoint:
          description: The API endpoint used by the batch.
          type: string
          readOnly: true
        errors:
          $ref: '#/components/schemas/BatchErrors'
        input_file_id:
          description: The ID of the input file for the batch.
          minLength: 1
          type: string
        completion_window:
          description: The time frame within which the batch should be processed.
          type: string
        status:
          $ref: '#/components/schemas/BatchStatus'
        output_file_id:
          description: The ID of the file containing outputs of successfully executed requests.
          type: string
        error_file_id:
          description: The ID of the file containing outputs of requests with errors.
          type: string
        created_at:
          format: unixtime
          description: A timestamp when this batch was created (in unix epochs).
          type: integer
          readOnly: true
        in_progress_at:
          format: unixtime
          description: A timestamp when this batch started progressing (in unix epochs).
          type: integer
          readOnly: true
        expires_at:
          format: unixtime
          description: A timestamp when this batch will expire (in unix epochs).
          type: integer
          readOnly: true
        finalizing_at:
          format: unixtime
          description: A timestamp when this batch started finalizing (in unix epochs).
          type: integer
          readOnly: true
        completed_at:
          format: unixtime
          description: A timestamp when this batch was completed (in unix epochs).
          type: integer
          readOnly: true
        failed_at:
          format: unixtime
          description: A timestamp when this batch failed (in unix epochs).
          type: integer
          readOnly: true
        expired_at:
          format: unixtime
          description: A timestamp when this batch expired (in unix epochs).
          type: integer
          readOnly: true
        cancelling_at:
          format: unixtime
          description: A timestamp when this batch started cancelling (in unix epochs).
          type: integer
          readOnly: true
        cancelled_at:
          format: unixtime
          description: A timestamp when this batch was cancelled (in unix epochs).
          type: integer
          readOnly: true
        request_counts:
          $ref: '#/components/schemas/BatchRequestCounts'
        metadata:
          description: A set of key-value pairs that can be attached to the batch. This can be useful for storing additional information about the batch in a structured format.
          type: object
          additionalProperties:
            type: string
    BatchErrors:
      title: BatchErrors
      description: For batches that have failed, this will contain more information on the cause of the failures.
      type: object
      properties:
        object:
          description: The type of the errors object. This is always 'list'.
          type: string
        data:
          $ref: '#/components/schemas/BatchErrorData'
    ErrorCode:
      title: ErrorCode
      description: 'Error codes as defined in the Microsoft REST guidelines

        (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
      - tooManyRequests
      - unauthorized
      - contentFilter
      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.
        - value: tooManyRequests
          description: Too many requests. Please retry later.
        - value: unauthorized
          description: The current user/api key is not authorized for the operation.
        - value: contentFilter
          description: Image generation failed as a result of our safety system.
    BatchRequestCounts:
      title: BatchRequestCounts
      description: The request counts for different statuses within the batch.
      type: object
      properties:
        total:
          description: The total number of requests in the batch.
          type: integer
        completed:
          description: The number of requests in the batch that have been completed successfully.
          type: integer
        failed:
          description: The number of requests in the batch that have failed.
          type: integer
    BatchStatus:
      title: BatchStatus
      description: The status of a batch.
      enum:
      - validating
      - failed
      - in_progress
      - finalizing
      - completed
      - expired
      - cancelling
      - cancelled
      type: string
      readOnly: true
      x-ms-enum:
        name: BatchStatus
        modelAsString: true
        values:
        - value: validating
          description: The input file is being validated before the batch can begin.
        - value: failed
          description: The input file has failed the validation process.
        - value: in_progress
          description: The input file was successfully validated and the batch is currently being executed.
        - value: finalizing
          description: The batch has completed and the results are being prepared.
        - value: completed
          description: The batch has been completed and the results are ready.
        - value: expired
          description: The batch was not able to complete within the 24-hour time window.
        - value: cancelling
          description: Cancellation of the batch has been initiated.
        - value: cancelled
          description: The batch was cancelled.
    TypeDiscriminator:
      title: TypeDiscriminator
      description: Defines the type of an object.
      enum:
      - list
      - fine_tuning.job
      - file
      - fine_tuning.job.event
      - fine_tuning.job.checkpoint
      - model
      - batch
      - upload
      - upload.part
      type: string
      readOnly: true
      x-ms-enum:
        name: TypeDiscriminator
        modelAsString: true
        values:
        - value: list
          description: This object represents a list of other objects.
        - value: fine_tuning.job
          description: This object represents a fine tune job.
        - value: file
          description: This object represents a file.
        - value: fine_tuning.job.event
          description: This object represents an event of a fine tuning job.
        - value: fine_tuning.job.checkpoint
          description: This object represents a checkpoint of a fine tuning job.
        - value: model
          description: This object represents a model (can be a base model or fine tune job result).
        - value: batch
          description: This object represents a batch.
        - value: upload
          description: This object represents a file upload.
        - value: upload.part
          description: This object represents part of a file upload.
    Error:
      title: Error
      description: 'Error content as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      required:
      - code
      - message
      type: object
      properties:
        code:
          $ref: '#/components/schemas/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: '#/components/schemas/Error'
        innererror:
          $ref: '#/components/schemas/InnerError'
      readOnly: true
    BatchesList:
      title: BatchList
      description: Represents a list of batches.
      type: object
      properties:
        object:
          $ref: '#/components/schemas/TypeDiscriminator'
        data:
          description: The list of items.
          type: array
          items:
            $ref: '#/components/schemas/Batch'
        first_id:
          description: The id of the first batch in the list of batches returned.
          type: string
        last_id:
          description: The id of the last batch in the list of batches returned.
          type: string
        has_more:
          description: A value indicating whether the list contains more elements than returned.
          type: boolean
    ErrorResponse:
      title: ErrorResponse
      description: 'Error response as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    InnerError:
      title: InnerError
      description: 'Inner error as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InnerErrorCode'
        innererror:
          $ref: '#/components/schemas/InnerError'
    InnerErrorCode:
      title: InnerErrorCode
      description: 'Inner error codes as defined in the Microsoft REST guidelines

        (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).'
      enum:
      - invalidPayload
      type: string
      x-ms-enum:
        name: InnerErrorCode
        modelAsString: true
        values:
        - value: invalidPayload
          description: The request data is invalid for this operation.
    BatchErrorData:
      title: BatchErrorData
      description: Error information for a failure in batch.
      type: object
      properties:
        code:
          description: An error code identifying the error type.
          type: string
        message:
          description: A human-readable message providing more details about the error.
          type: string
        param:
          description: The name of the parameter that caused the error, if applicable (can be null).
          type: string
        line:
          description: The line number of the input file where the error occurred, if applicable (can be null).
          type: string
    BatchCreateRequest:
      title: BatchCreateRequest
      description: Defines the request to create a batch.
      required:
      - input_file_id
      - endpoint
      - completion_window
      type: object
      properties:
        input_file_id:
          description: The ID if the input file for the batch.
          minLength: 1
          type: string
        endpoint:
          description: The API endpoint used by the batch.
          type: string
        completion_window:
          description: The time frame within which the batch should be processed.
          type: string
        metadata:
          description: A set of key-value pairs that can be attached to the batch. This can be useful for storing additional information about the batch in a structured format.
          type: object
          additionalProperties:
            type: string
  parameters:
    apiVersionQueryParameter:
      in: query
      name: api-version
      description: The requested API version.
      required: true
      x-ms-client-default: '2024-10-21'
      x-ms-parameter-location: client
      schema:
        type: string
  securitySchemes:
    api-key:
      type: apiKey
      name: api-key
      in: header
      description: Provide your Cognitive Services Azure OpenAI account key here.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/openai'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/endpoint'