> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hicap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat completions

> [!NOTE]
>
> Choose an exact compatible ID from [the model list](https://docs.hicap.ai/api-reference/models.md). Supported parameters and output formats vary by model and connection; this schema does not guarantee every upstream feature. See [endpoint availability](https://docs.hicap.ai/api-reference/introduction.md#endpoint-availability).


## OpenAPI

````yaml post /chat/completions
openapi: 3.1.0
info:
  title: Hicap API
  description: >-
    OpenAI-compatible request reference. Authenticate using the api-key header.
    Listed paths and request shapes do not guarantee support for every model,
    connection, backend, or parameter; see
    https://docs.hicap.ai/api-reference/introduction.
  version: 1.0.0
  contact:
    name: Hicap Support
    email: support@hicap.ai
servers:
  - url: https://api.hicap.ai/v1
security:
  - apiKeyAuth: []
paths:
  /chat/completions:
    post:
      summary: Creates a model response for the given chat conversation
      operationId: ChatCompletions_Create
      parameters:
        - name: x-hicap-tags
          in: header
          required: false
          description: >-
            One JSON object mapping dimension keys to short string values. Never
            include secrets or direct personal identifiers. Opaque identity
            references require approved policy and verified destination
            handling; see the identity attribution guide.
          schema:
            type: string
          example: '{"feature":"support","env":"production"}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createChatCompletionRequest'
            example:
              model: gpt-4o-mini
              messages:
                - role: user
                  content: >-
                    Summarize the support case: a duplicate charge was confirmed
                    and a refund is pending.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-sent event stream for compatible streaming requests.
                  Event format and availability must be verified for the
                  selected model and backend.
          headers:
            apim-request-id:
              description: Request ID for troubleshooting purposes
              schema:
                type: string
        default:
          description: >-
            Gateway or backend error. Body shape varies; inspect HTTP status
            before parsing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  message:
                    type: string
                  error:
                    type: object
                    additionalProperties: true
                additionalProperties: true
components:
  schemas:
    createChatCompletionRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/chatCompletionsRequestCommon'
        - properties:
            messages:
              description: >-
                A list of messages comprising the conversation so far. Depending
                on the model you use, different message types (modalities) are
                supported, like text, images, and audio.
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/chatCompletionRequestMessage'
            modalities:
              $ref: '#/components/schemas/ChatCompletionModalities'
            audio:
              type: object
              description: >-
                Optional upstream-compatible audio output settings. Model and
                connection support, accepted voice identifiers, and output
                formats have not been verified.
              required:
                - voice
                - format
              x-oaiExpandable: true
              properties:
                voice:
                  description: >-
                    Upstream-compatible voice identifier or custom voice
                    reference. Availability depends on the selected model and
                    connection.
                  oneOf:
                    - type: string
                      enum:
                        - alloy
                        - ash
                        - ballad
                        - coral
                        - echo
                        - fable
                        - nova
                        - onyx
                        - sage
                        - shimmer
                        - marin
                        - cedar
                    - type: object
                      title: id
                      description: Custom voice reference.
                      properties:
                        id:
                          type: string
                          description: The custom voice ID, e.g. `voice_1234`.
                      required:
                        - id
                format:
                  type: string
                  enum:
                    - wav
                    - mp3
                    - flac
                    - opus
                    - pcm16
                  description: >-
                    Upstream-compatible output format. Availability depends on
                    the selected model and connection.
            reasoning_effort:
              type: string
              description: >-
                Optional upstream-compatible reasoning effort. Supported values
                and behavior depend on the selected model and backend; verify
                before use.
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
            logit_bias:
              type: object
              default: null
              nullable: true
              additionalProperties:
                type: integer
            logprobs:
              description: >-
                Whether to return log probabilities of the output tokens or not.
                If true, returns the log probabilities of each output token
                returned in the `content` of `message`.
              type: boolean
              default: false
              nullable: true
            top_logprobs:
              description: >-
                An integer between 0 and 20 specifying the number of most likely
                tokens to return at each token position, each with an associated
                log probability.
              type: integer
              minimum: 0
              maximum: 20
              nullable: true
            'n':
              type: integer
              minimum: 1
              maximum: 128
              default: 1
              example: 1
              nullable: true
              description: >-
                How many chat completion choices to generate for each input
                message. Note that you will be charged based on the number of
                generated tokens across all of the choices. Keep `n` as `1` to
                minimize costs.
            prediction:
              nullable: true
              x-oaiExpandable: true
              description: >-
                Configuration for a [Predicted
                Output](https://platform.openai.com/docs/guides/predicted-outputs),
                which can greatly improve response times when large parts of the
                model response are known ahead of time. This is most common when
                you are regenerating a file with only minor changes to most of
                the content.
              oneOf:
                - $ref: '#/components/schemas/PredictionContent'
            response_format:
              description: >-
                Optional response format. JSON and JSON Schema modes, accepted
                schemas, and output behavior depend on the selected model and
                connection. Verify provider acceptance and validate each
                response; a request field or schema does not guarantee valid or
                schema-conformant output.
              oneOf:
                - $ref: '#/components/schemas/ResponseFormatText'
                - $ref: '#/components/schemas/ResponseFormatJsonObject'
                - $ref: '#/components/schemas/ResponseFormatJsonSchema'
              x-oaiExpandable: true
            seed:
              type: integer
              nullable: true
              deprecated: true
              description: >-
                Optional seed. Support, accepted range, and repeatability depend
                on the selected model and backend and have not been verified.
                JavaScript cannot exactly represent all large integers; avoid
                values outside its safe integer range unless the client and
                backend support them.
            stream_options:
              $ref: '#/components/schemas/chatCompletionStreamOptions'
              nullable: true
              default: null
            tools:
              type: array
              description: >-
                A list of tools the model may call. You can provide either
                [custom
                tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
                or [function
                tools](https://platform.openai.com/docs/guides/function-calling).
              items:
                $ref: '#/components/schemas/chatCompletionTool'
            tool_choice:
              $ref: '#/components/schemas/chatCompletionToolChoiceOption'
            function_call:
              deprecated: true
              description: >
                Deprecated in favor of `tool_choice`.


                Controls which (if any) function is called by the model.

                `none` means the model will not call a function and instead
                generates a message.

                `auto` means the model can pick between generating a message or
                calling a function.

                Specifying a particular function via `{"name": "my_function"}`
                forces the model to call that function.


                `none` is the default when no functions are present. `auto` is
                the default if functions are present.
              oneOf:
                - type: string
                  description: >
                    `none` means the model will not call a function and instead
                    generates a message. `auto` means the model can pick between
                    generating a message or calling a function.
                  enum:
                    - none
                    - auto
                - $ref: '#/components/schemas/chatCompletionFunctionCallOption'
              x-oaiExpandable: true
            functions:
              deprecated: true
              description: |
                Deprecated in favor of `tools`.

                A list of functions the model may generate JSON inputs for.
              type: array
              minItems: 1
              maxItems: 128
              items:
                $ref: '#/components/schemas/chatCompletionFunctions'
            max_tokens:
              description: >-
                The maximum number of
                [tokens](https://platform.openai.com/tokenizer) that can be
                generated in the chat completion. This value can be used to
                control costs for text generated via API.


                This value is now deprecated in favor of
                `max_completion_tokens`.
              type: integer
              nullable: true
              deprecated: true
            parallel_tool_calls:
              description: >-
                Whether to enable [parallel function
                calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling)
                during tool use.
              type: boolean
              nullable: true
            prompt_cache_retention:
              type: string
              description: >-
                Optional upstream-compatible cache retention setting. Support,
                duration, and actual data handling depend on the selected
                backend and have not been verified for every Hicap connection.
            service_tier:
              $ref: '#/components/schemas/serviceTier'
            verbosity:
              type: string
              description: >-
                Optional upstream-compatible verbosity setting. Supported values
                and behavior depend on the selected model and backend.
              enum:
                - low
                - medium
                - high
              default: medium
            web_search_options:
              type: object
              description: >-
                Optional upstream-compatible web search settings. Availability,
                behavior, and external data handling must be verified for the
                selected model and connection.
              properties:
                search_context_size:
                  type: string
                  enum:
                    - low
                    - medium
                    - high
                user_location:
                  type: object
                  description: Approximate location parameters for the search.
                  properties:
                    approximate:
                      type: object
                      description: Approximate location parameters for the search.
                      properties:
                        city:
                          type: string
                          description: >-
                            Free text input for the city of the user, e.g. `San
                            Francisco`.
                        country:
                          type: string
                          description: >-
                            The two-letter [ISO country
                            code](https://en.wikipedia.org/wiki/ISO_3166-1) of
                            the user, e.g. `US`.
                        region:
                          type: string
                          description: >-
                            Free text input for the region of the user, e.g.
                            `California`.
                        timezone:
                          type: string
                          description: >-
                            The [IANA
                            timezone](https://timeapi.io/documentation/iana-timezones)
                            of the user, e.g. `America/Los_Angeles`.
                    type:
                      type: string
                      description: >-
                        The type of location approximation. Always
                        `approximate`.
                      enum:
                        - approximate
                  required:
                    - approximate
                    - type
          required:
            - messages
            - model
    createChatCompletionResponse:
      type: object
      description: >-
        Represents a chat completion response returned by model, based on the
        provided input.
      title: Chat Completion
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        choices:
          type: array
          description: >-
            A list of chat completion choices. Can be more than one if `n` is
            greater than 1.
          items:
            type: object
            required:
              - finish_reason
              - index
              - message
              - logprobs
            properties:
              finish_reason:
                type: string
                description: >
                  The reason the model stopped generating tokens. This will be
                  `stop` if the model hit a natural stop point or a provided
                  stop sequence,

                  `length` if the maximum number of tokens specified in the
                  request was reached,

                  `content_filter` if content was omitted due to a flag from our
                  content filters,

                  `tool_calls` if the model called a tool, or `function_call`
                  (deprecated) if the model called a function.
                enum:
                  - stop
                  - length
                  - tool_calls
                  - content_filter
                  - function_call
              index:
                type: integer
                description: The index of the choice in the list of choices.
              message:
                $ref: '#/components/schemas/chatCompletionResponseMessage'
              logprobs:
                description: Log probability information for the choice.
                type: object
                nullable: true
                properties:
                  content:
                    description: >-
                      A list of message content tokens with log probability
                      information.
                    type: array
                    items:
                      $ref: '#/components/schemas/chatCompletionTokenLogprob'
                    nullable: true
                  refusal:
                    description: >-
                      A list of message refusal tokens with log probability
                      information.
                    type: array
                    items:
                      $ref: '#/components/schemas/chatCompletionTokenLogprob'
                    nullable: true
                required:
                  - content
                  - refusal
        created:
          type: integer
          description: >-
            The Unix timestamp (in seconds) of when the chat completion was
            created.
        model:
          type: string
          description: The model used for the chat completion.
        system_fingerprint:
          type: string
          description: >
            This fingerprint represents the backend configuration that the model
            runs with.


            Can be used in conjunction with the `seed` request parameter to
            understand when backend changes have been made that might impact
            determinism.
          deprecated: true
        object:
          type: string
          description: The object type, which is always `chat.completion`.
          enum:
            - chat.completion
        service_tier:
          $ref: '#/components/schemas/serviceTier'
        usage:
          $ref: '#/components/schemas/completionUsage'
    chatCompletionsRequestCommon:
      type: object
      properties:
        model:
          type: string
          description: >-
            Model ID used to generate the response. See the list of [available
            options](https://hicap.ai/models)
          default: gpt-5.2
        temperature:
          description: >-
            What sampling temperature to use, between 0 and 2. Higher values
            like 0.8 will make the output more random, while lower values like
            0.2 will make it more focused and deterministic.

            We generally recommend altering this or `top_p` but not both.
          type: number
          minimum: 0
          maximum: 2
          default: 1
          example: 1
          nullable: true
        top_p:
          description: >-
            An alternative to sampling with temperature, called nucleus
            sampling, where the model considers the results of the tokens with
            top_p probability mass. So 0.1 means only the tokens comprising the
            top 10% probability mass are considered.

            We generally recommend altering this or `temperature` but not both.
          type: number
          minimum: 0
          maximum: 1
          example: 1
          nullable: true
        stream:
          description: >-
            Requests an OpenAI-compatible server-sent event stream when
            supported by the model and connection. Live streaming behavior and
            content type have not been verified for this documentation update.
          type: boolean
          nullable: true
          default: false
        stop:
          description: >-
            Up to 4 sequences where the API will stop generating further tokens.
            The returned text will not contain the stop sequence.
          oneOf:
            - type: string
              nullable: true
            - type: array
              items:
                type: string
                nullable: false
              minItems: 1
              maxItems: 4
              description: Array minimum size of 1 and maximum of 4
          default: null
        max_completion_tokens:
          description: >-
            An upper bound for the number of tokens that can be generated for a
            completion, including visible output tokens and [reasoning
            tokens](https://platform.openai.com/docs/guides/reasoning).
          type: integer
          nullable: true
        presence_penalty:
          description: >-
            Number between -2.0 and 2.0. Positive values penalize new tokens
            based on whether they appear in the text so far, increasing the
            model's likelihood to talk about new topics.
          type: number
          default: 0
          minimum: -2
          maximum: 2
        frequency_penalty:
          description: >-
            Number between -2.0 and 2.0. Positive values penalize new tokens
            based on their existing frequency in the text so far, decreasing the
            model's likelihood to repeat the same line verbatim.
          type: number
          default: 0
          minimum: -2
          maximum: 2
        logit_bias:
          description: >-
            Modify the likelihood of specified tokens appearing in the
            completion.


            Accepts a json object that maps tokens (specified by their token ID
            in the tokenizer) to an associated bias value from -100 to 100.
            Mathematically, the bias is added to the logits generated by the
            model prior to sampling. The exact effect will vary per model, but
            values between -1 and 1 should decrease or increase likelihood of
            selection; values like -100 or 100 should result in a ban or
            exclusive selection of the relevant token.
          type: object
          nullable: true
        store:
          description: >-
            Optional upstream-compatible field. Support and any storage or
            retention behavior have not been verified for every Hicap model and
            connection. Do not assume that enabling it stores responses or makes
            them available for training or evaluation.
          type: boolean
          nullable: true
          default: false
        metadata:
          description: >-
            Optional request metadata. Acceptance, persistence, access, and
            retrieval are not verified for every model and connection. Do not
            put secrets or sensitive personal data in this field.
          type: object
          nullable: true
          additionalProperties:
            type: string
            maxLength: 512
        user:
          description: >-
            Optional upstream-compatible user reference. Verify support and
            approved identity handling for your selected model, connection, and
            destination before sending an identifier.
          type: string
          nullable: false
          deprecated: true
        safety_identifier:
          description: >-
            Optional upstream-compatible safety identifier. Support and
            destination handling are unverified. Treat opaque or hashed
            identifiers as potentially personal data; do not send them without
            an approved policy.
          type: string
          nullable: false
        prompt_cache_key:
          description: >-
            Optional upstream-compatible cache key. Acceptance, caching
            behavior, and retention are model- and backend-dependent and have
            not been verified for every Hicap connection.
          type: string
          nullable: false
    chatCompletionRequestMessage:
      oneOf:
        - $ref: '#/components/schemas/ChatCompletionRequestDeveloperMessage'
        - $ref: '#/components/schemas/chatCompletionRequestSystemMessage'
        - $ref: '#/components/schemas/chatCompletionRequestUserMessage'
        - $ref: '#/components/schemas/chatCompletionRequestAssistantMessage'
        - $ref: '#/components/schemas/chatCompletionRequestToolMessage'
        - $ref: '#/components/schemas/chatCompletionRequestFunctionMessage'
    ChatCompletionModalities:
      type: array
      description: >-
        Optional output modalities. Supported values and response formats depend
        on the selected model and connection; verify before use.
      items:
        type: string
        enum:
          - text
          - audio
    PredictionContent:
      type: object
      title: Static Content
      description: >-
        Static predicted output content, such as the content of a text file that
        is being regenerated.
      required:
        - content
        - type
      properties:
        type:
          type: string
          description: >-
            The type of the predicted content you want to provide. This type is
            currently always `content`.
          enum:
            - content
        content:
          x-oaiExpandable: true
          description: >-
            The content that should be matched when generating a model response.
            If generated tokens would match this content, the entire model
            response can be returned much more quickly.
          oneOf:
            - type: string
              title: Text Content
              description: >-
                The content used for a Predicted Output. This is often the text
                of a file you are regenerating with minor changes.
            - type: array
              title: Array of content parts
              description: >-
                An array of content parts with a defined type. Supported options
                differ based on the model being used to generate the response.
                Can contain text inputs.
              minItems: 1
              items:
                $ref: >-
                  #/components/schemas/chatCompletionRequestMessageContentPartText
    ResponseFormatText:
      type: object
      title: Text
      description: Default response format. Used to generate text responses.
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `text`
          enum:
            - text
      required:
        - type
    ResponseFormatJsonObject:
      type: object
      title: JSON Object
      description: >-
        JSON object response format. An older method of generating JSON
        responses. Using `json_schema` is recommended for models that support
        it. Note that the model will not generate JSON without a system or user
        message instructing it to do so.
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `json_object`
          enum:
            - json_object
      required:
        - type
    ResponseFormatJsonSchema:
      type: object
      title: JSON Schema
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `json_schema`
          enum:
            - json_schema
        json_schema:
          type: object
          description: Structured Outputs configuration options, including a JSON Schema.
          properties:
            description:
              type: string
              description: >-
                A description of what the response format is for, used by the
                model to determine how to respond in the format.
            name:
              type: string
              description: >-
                The name of the response format. Must be a-z, A-Z, 0-9, or
                contain underscores and dashes, with a maximum length of 64.
              maxLength: 64
            schema:
              $ref: '#/components/schemas/ResponseFormatJsonSchemaSchema'
            strict:
              type: boolean
              nullable: true
              default: false
              description: >-
                Whether to enable strict schema adherence when generating the
                output. If set to true, the model will always follow the exact
                schema defined in the `schema` field. Only a subset of JSON
                Schema is supported when `strict` is `true`. To learn more, read
                the [Structured Outputs
                guide](https://platform.openai.com/docs/guides/structured-outputs).
          required:
            - schema
            - name
      required:
        - type
        - json_schema
    chatCompletionStreamOptions:
      description: >
        Options for streaming response. Only set this when you set `stream:
        true`.
      type: object
      nullable: true
      default: null
      properties:
        include_obfuscation:
          type: boolean
          description: >-
            Optional upstream-compatible streaming option. Support and behavior
            depend on the selected backend and have not been verified.
        include_usage:
          type: boolean
          description: >
            If set, an additional chunk will be streamed before the `data:
            [DONE]` message. The `usage` field on this chunk shows the token
            usage statistics for the entire request, and the `choices` field
            will always be an empty array.

             All other chunks will also include a `usage` field, but with a null value. **NOTE**: If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request.
    chatCompletionTool:
      type: object
      oneOf:
        - type: object
          description: A function tool that can be used to generate a response.
          title: Function Tool
          properties:
            type:
              type: string
              enum:
                - function
              description: The type of the tool. Currently, only `function` is supported.
            function:
              $ref: '#/components/schemas/FunctionObject'
          required:
            - type
            - function
        - type: object
          description: A custom tool that processes input using a specified format.
          title: Custom tool
          properties:
            type:
              type: string
              enum:
                - custom
              description: The type of the custom tool. Always `custom`.
            custom:
              type: object
              description: Properties of the custom tool.
              properties:
                name:
                  type: string
                  description: >-
                    The name of the custom tool, used to identify it in tool
                    calls.
                description:
                  type: string
                  description: >-
                    Optional description of the custom tool, used to provide
                    more context.
                format:
                  type: object
                  description: >-
                    The input format for the custom tool. Default is
                    unconstrained text.
                  oneOf:
                    - title: Text format
                      type: object
                      description: Unconstrained free-form text.
                      properties:
                        type:
                          type: string
                          description: Unconstrained text format. Always `text`.
                          enum:
                            - text
                      required:
                        - type
                    - title: Grammar format
                      type: object
                      description: A grammar defined by the user.
                      properties:
                        type:
                          type: string
                          description: Grammar format. Always `grammar`.
                          enum:
                            - grammar
                        grammar:
                          type: object
                          description: Your chosen grammar.
                          properties:
                            definition:
                              type: string
                              description: The grammar definition.
                            syntax:
                              type: string
                              description: >-
                                The syntax of the grammar definition. One of
                                `lark` or `regex`.
                              enum:
                                - lark
                                - regex
                          required:
                            - definition
                            - syntax
                      required:
                        - type
                        - grammar
              required:
                - name
          required:
            - type
            - custom
    chatCompletionToolChoiceOption:
      description: >+
        Controls which (if any) tool is called by the model. `none` means the
        model will not call any tool and instead generates a message. `auto`
        means the model can pick between generating a message or calling one or
        more tools. `required` means the model must call one or more tools.
        Specifying a particular tool via `{"type": "function", "function":
        {"name": "my_function"}}` forces the model to call that tool.


        `none` is the default when no tools are present.


        `auto` is the default if tools are present.

      oneOf:
        - type: string
          title: Tool choice mode
          description: >-
            `none` means the model will not call a function and instead
            generates a message. `auto` means the model can pick between
            generating a message or calling one or more tools. `required` means
            the model must call one or more tools.
          enum:
            - none
            - auto
            - required
        - $ref: '#/components/schemas/chatCompletionNamedToolChoice'
    chatCompletionFunctionCallOption:
      type: object
      description: >
        Specifying a particular function via `{"name": "my_function"}` forces
        the model to call that function.
      properties:
        name:
          type: string
          description: The name of the function to call.
      required:
        - name
    chatCompletionFunctions:
      type: object
      deprecated: true
      properties:
        description:
          type: string
          description: >-
            A description of what the function does, used by the model to choose
            when and how to call the function.
        name:
          type: string
          description: >-
            The name of the function to be called. Must be a-z, A-Z, 0-9, or
            contain underscores and dashes, with a maximum length of 64.
          maxLength: 64
        parameters:
          $ref: '#/components/schemas/FunctionParameters'
      required:
        - name
    serviceTier:
      type: string
      description: >-
        Optional upstream-compatible service tier. Availability, routing,
        pricing, and response behavior depend on the selected model and
        connection and have not been verified for every backend.
      enum:
        - auto
        - default
        - flex
        - priority
      default: auto
      nullable: true
    chatCompletionResponseMessage:
      type: object
      description: A chat completion message generated by the model.
      properties:
        role:
          $ref: '#/components/schemas/chatCompletionResponseMessageRole'
        refusal:
          type: string
          description: The refusal message generated by the model.
          nullable: true
        content:
          type: string
          description: The contents of the message.
          nullable: true
        tool_calls:
          type: array
          description: The tool calls generated by the model, such as function calls.
          items:
            oneOf:
              - $ref: '#/components/schemas/chatCompletionMessageToolCall'
              - $ref: '#/components/schemas/chatCompletionMessageCustomToolCall'
        function_call:
          $ref: '#/components/schemas/chatCompletionFunctionCall'
        audio:
          type: object
          description: >
            If the audio output modality is requested, this object contains data

            about the audio response from the model. [Learn
            more](/docs/guides/audio).
          x-oaiExpandable: true
          required:
            - id
            - expires_at
            - data
            - transcript
          properties:
            id:
              type: string
              description: Unique identifier for this audio response.
            expires_at:
              type: integer
              description: >
                The Unix timestamp (in seconds) for when this audio response
                will

                no longer be accessible on the server for use in multi-turn

                conversations.
            data:
              type: string
              description: |
                Base64 encoded audio bytes generated by the model, in the format
                specified in the request.
            transcript:
              type: string
              description: Transcript of the audio generated by the model.
        annotations:
          type: array
          description: >-
            Annotations for the message, when applicable, as when using the [web
            search
            tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
          items:
            type: object
            properties:
              type:
                type: string
                description: The type of the URL citation. Always `url_citation`.
                enum:
                  - url_citation
              url_citation:
                type: object
                description: A URL citation when using web search.
                properties:
                  end_index:
                    type: integer
                    description: >-
                      The index of the last character of the URL citation in the
                      message.
                  start_index:
                    type: integer
                    description: >-
                      The index of the first character of the URL citation in
                      the message.
                  title:
                    type: string
                    description: The title of the web resource.
                  url:
                    type: string
                    description: The URL of the web resource.
                required:
                  - end_index
                  - start_index
                  - url
      required:
        - role
        - content
        - refusal
    chatCompletionTokenLogprob:
      type: object
      properties:
        token:
          description: The token.
          type: string
        logprob:
          description: The log probability of this token.
          type: number
        bytes:
          description: >-
            A list of integers representing the UTF-8 bytes representation of
            the token. Useful in instances where characters are represented by
            multiple tokens and their byte representations must be combined to
            generate the correct text representation. Can be `null` if there is
            no bytes representation for the token.
          type: array
          items:
            type: integer
          nullable: true
        top_logprobs:
          description: >-
            List of the most likely tokens and their log probability, at this
            token position. In rare cases, there may be fewer than the number of
            requested `top_logprobs` returned.
          type: array
          items:
            type: object
            properties:
              token:
                description: The token.
                type: string
              logprob:
                description: The log probability of this token.
                type: number
              bytes:
                description: >-
                  A list of integers representing the UTF-8 bytes representation
                  of the token. Useful in instances where characters are
                  represented by multiple tokens and their byte representations
                  must be combined to generate the correct text representation.
                  Can be `null` if there is no bytes representation for the
                  token.
                type: array
                items:
                  type: integer
                nullable: true
            required:
              - token
              - logprob
              - bytes
      required:
        - token
        - logprob
        - bytes
        - top_logprobs
    completionUsage:
      type: object
      description: Usage statistics for the completion request.
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt.
        completion_tokens:
          type: integer
          description: Number of tokens in the generated completion.
        total_tokens:
          type: integer
          description: Total number of tokens used in the request (prompt + completion).
        prompt_tokens_details:
          type: object
          description: Details of the prompt tokens.
          properties:
            audio_tokens:
              type: integer
              description: Audio input tokens present in the prompt.
            cached_tokens:
              type: integer
              description: The number of cached prompt tokens.
        completion_tokens_details:
          type: object
          description: Breakdown of tokens used in a completion.
          properties:
            accepted_prediction_tokens:
              type: integer
              description: >-
                When using Predicted Outputs, the number of tokens in the
                prediction that appeared in the completion.
            audio_tokens:
              type: integer
              description: Audio input tokens generated by the model.
            reasoning_tokens:
              type: integer
              description: Tokens generated by the model for reasoning.
            rejected_prediction_tokens:
              type: integer
              description: >-
                When using Predicted Outputs, the number of tokens in the
                prediction that did not appear in the completion. However, like
                reasoning tokens, these tokens are still counted in the total 
                completion tokens for purposes of billing, output, and context
                window limits.
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
    ChatCompletionRequestDeveloperMessage:
      type: object
      title: Developer message
      description: >-
        Developer-provided instructions that the model should follow, regardless
        of messages sent by the user.
      properties:
        content:
          description: The contents of the developer message.
          oneOf:
            - type: string
              description: The contents of the developer message.
              title: Text content
            - type: array
              description: >-
                An array of content parts with a defined type. For developer
                messages, only type `text` is supported.
              title: Array of content parts
              items:
                $ref: >-
                  #/components/schemas/chatCompletionRequestDeveloperMessageContentPart
              minItems: 1
        role:
          type: string
          enum:
            - developer
          description: The role of the messages author, in this case `developer`.
        name:
          type: string
          description: >-
            An optional name for the participant. Provides the model information
            to differentiate between participants of the same role.
      required:
        - content
        - role
    chatCompletionRequestSystemMessage:
      type: object
      title: System message
      description: >-
        Developer-provided instructions that the model should follow, regardless
        of messages sent by the user.
      properties:
        content:
          description: The contents of the system message.
          oneOf:
            - type: string
              description: The contents of the system message.
              title: Text content
            - type: array
              description: >-
                An array of content parts with a defined type. For system
                messages, only type `text` is supported.
              title: Array of content parts
              items:
                $ref: >-
                  #/components/schemas/chatCompletionRequestSystemMessageContentPart
              minItems: 1
        role:
          type: string
          enum:
            - system
          description: The role of the messages author, in this case `system`.
        name:
          type: string
          description: >-
            An optional name for the participant. Provides the model information
            to differentiate between participants of the same role.
      required:
        - content
        - role
    chatCompletionRequestUserMessage:
      type: object
      title: User message
      description: >-
        Messages sent by an end user, containing prompts or additional context
        information.
      allOf:
        - not:
            required:
              - name
            properties:
              name:
                const: developer
      properties:
        content:
          description: |
            The contents of the user message.
          oneOf:
            - type: string
              description: The text contents of the message.
              title: Text content
            - type: array
              description: >-
                An array of content parts with a defined type. Supported options
                differ based on the model being used to generate the response.
                Can contain text, image, or audio inputs.
              title: Array of content parts
              items:
                $ref: >-
                  #/components/schemas/chatCompletionRequestUserMessageContentPart
              minItems: 1
          x-oaiExpandable: true
        role:
          type: string
          enum:
            - user
          description: The role of the messages author, in this case `user`.
        name:
          type: string
          description: >-
            An optional name for the participant. Provides the model information
            to differentiate between participants of the same role.
      required:
        - content
        - role
    chatCompletionRequestAssistantMessage:
      type: object
      title: Assistant message
      description: Messages sent by the model in response to user messages.
      properties:
        content:
          nullable: true
          oneOf:
            - type: string
              description: The contents of the assistant message.
              title: Text content
            - type: array
              description: >-
                An array of content parts with a defined type. Can be one or
                more of type `text`, or exactly one of type `refusal`.
              title: Array of content parts
              items:
                $ref: >-
                  #/components/schemas/chatCompletionRequestAssistantMessageContentPart
              minItems: 1
          description: >
            The contents of the assistant message. Required unless `tool_calls`
            or `function_call` is specified.
        refusal:
          nullable: true
          type: string
          description: The refusal message by the assistant.
        role:
          type: string
          enum:
            - assistant
          description: The role of the messages author, in this case `assistant`.
        audio:
          type: object
          description: >-
            Data about a previous audio response from the model. [Learn
            more](https://platform.openai.com/docs/guides/audio).
          properties:
            id:
              type: string
              description: Unique identifier for a previous audio response from the model.
          required:
            - id
        name:
          type: string
          description: >-
            An optional name for the participant. Provides the model information
            to differentiate between participants of the same role.
        tool_calls:
          $ref: '#/components/schemas/chatCompletionMessageToolCalls'
        function_call:
          type: object
          deprecated: true
          description: >-
            Deprecated and replaced by `tool_calls`. The name and arguments of a
            function that should be called, as generated by the model.
          nullable: true
          properties:
            arguments:
              type: string
              description: >-
                The arguments to call the function with, as generated by the
                model in JSON format. Note that the model does not always
                generate valid JSON, and may hallucinate parameters not defined
                by your function schema. Validate the arguments in your code
                before calling your function.
            name:
              type: string
              description: The name of the function to call.
          required:
            - arguments
            - name
      required:
        - role
    chatCompletionRequestToolMessage:
      type: object
      title: Tool message
      properties:
        role:
          type: string
          enum:
            - tool
          description: The role of the messages author, in this case `tool`.
        content:
          oneOf:
            - type: string
              description: The contents of the tool message.
              title: Text content
            - type: array
              description: >-
                An array of content parts with a defined type. For tool
                messages, only type `text` is supported.
              title: Array of content parts
              items:
                $ref: >-
                  #/components/schemas/chatCompletionRequestToolMessageContentPart
              minItems: 1
          description: The contents of the tool message.
        tool_call_id:
          type: string
          description: Tool call that this message is responding to.
      required:
        - role
        - content
        - tool_call_id
    chatCompletionRequestFunctionMessage:
      type: object
      title: Function message
      deprecated: true
      properties:
        role:
          type: string
          enum:
            - function
          description: The role of the messages author, in this case `function`.
        content:
          nullable: true
          type: string
          description: The contents of the function message.
        name:
          type: string
          description: The name of the function to call.
      required:
        - role
        - content
        - name
    chatCompletionRequestMessageContentPartText:
      type: object
      title: Text content part
      properties:
        type:
          type: string
          enum:
            - text
          description: The type of the content part.
        text:
          type: string
          description: The text content.
      required:
        - type
        - text
    ResponseFormatJsonSchemaSchema:
      type: object
      description: >-
        The schema for the response format, described as a JSON Schema object.
        Learn how to build JSON schemas [here](https://json-schema.org/).
      additionalProperties: true
    FunctionObject:
      type: object
      properties:
        description:
          type: string
          description: >-
            A description of what the function does, used by the model to choose
            when and how to call the function.
        name:
          type: string
          description: >-
            The name of the function to be called. Must be a-z, A-Z, 0-9, or
            contain underscores and dashes, with a maximum length of 64.
        parameters:
          $ref: '#/components/schemas/FunctionParameters'
        strict:
          type: boolean
          nullable: true
          default: false
          description: >-
            Whether to enable strict schema adherence when generating the
            function call. If set to true, the model will follow the exact
            schema defined in the `parameters` field. Only a subset of JSON
            Schema is supported when `strict` is `true`. Learn more about
            Structured Outputs in the [function calling
            guide](https://platform.openai.com/docs/guides/function-calling).
      required:
        - name
    chatCompletionNamedToolChoice:
      type: object
      oneOf:
        - type: object
          title: Allowed tools
          description: Constrains the tools available to the model to a pre-defined set.
          properties:
            type:
              type: string
              enum:
                - allowed_tools
              description: Allowed tool configuration type. Always `allowed_tools`.
            allowed_tools:
              type: object
              description: >-
                Constrains the tools available to the model to a pre-defined
                set.
              properties:
                mode:
                  type: string
                  description: >-
                    Constrains the tools available to the model to a pre-defined
                    set.


                    `auto` allows the model to pick from among the allowed tools
                    and generate a message.


                    `required` requires the model to call one or more of the
                    allowed tools.
                  enum:
                    - auto
                    - required
                tools:
                  type: array
                  description: >-
                    A list of tool definitions that the model should be allowed
                    to call.


                    For the Chat Completions API, the list of tool definitions
                    might look like:
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - function
                      function:
                        type: object
                        properties:
                          name:
                            type: string
              required:
                - mode
                - tools
          required:
            - type
            - allowed_tools
        - type: object
          title: Function tool choice
          description: >-
            Specifies a tool the model should use. Use to force the model to
            call a specific function.
          properties:
            type:
              type: string
              enum:
                - function
              description: For function calling, the type is always `function`.
            function:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the function to call.
              required:
                - name
          required:
            - type
            - function
        - type: object
          title: Custom tool choice
          description: >-
            Specifies a tool the model should use. Use to force the model to
            call a specific custom tool.
          properties:
            type:
              type: string
              enum:
                - custom
              description: For custom tool calling, the type is always `custom`.
            custom:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the custom tool to call.
              required:
                - name
          required:
            - type
            - custom
    FunctionParameters:
      type: object
      description: >-
        The parameters the functions accepts, described as a JSON Schema object.
        See the
        [guide](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/function-calling)
        for examples, and the [JSON Schema
        reference](https://json-schema.org/understanding-json-schema/) for
        documentation about the format. 


        Omitting `parameters` defines a function with an empty parameter list.
      additionalProperties: true
    chatCompletionResponseMessageRole:
      type: string
      enum:
        - assistant
      description: The role of the author of the response message.
    chatCompletionMessageToolCall:
      type: object
      title: Function tool call
      description: A call to a function tool created by the model.
      properties:
        id:
          type: string
          description: The ID of the tool call.
        type:
          $ref: '#/components/schemas/toolCallType'
        function:
          type: object
          description: The function that the model called.
          properties:
            name:
              type: string
              description: The name of the function to call.
            arguments:
              type: string
              description: >-
                The arguments to call the function with, as generated by the
                model in JSON format. Note that the model does not always
                generate valid JSON, and may hallucinate parameters not defined
                by your function schema. Validate the arguments in your code
                before calling your function.
          required:
            - name
            - arguments
      required:
        - id
        - type
        - function
    chatCompletionMessageCustomToolCall:
      type: object
      title: Custom tool call
      description: A call to a custom tool created by the model.
      properties:
        id:
          type: string
          description: The ID of the tool call.
        type:
          $ref: '#/components/schemas/customToolCallType'
        custom:
          type: object
          description: The custom tool that the model called.
          properties:
            name:
              type: string
              description: The name of the custom tool to call.
            input:
              type: string
              description: The input for the custom tool call generated by the model.
          required:
            - name
            - input
      required:
        - id
        - type
        - custom
    chatCompletionFunctionCall:
      type: object
      description: >-
        Deprecated and replaced by `tool_calls`. The name and arguments of a
        function that should be called, as generated by the model.
      properties:
        name:
          type: string
          description: The name of the function to call.
        arguments:
          type: string
          description: >-
            The arguments to call the function with, as generated by the model
            in JSON format. Note that the model does not always generate valid
            JSON, and may hallucinate parameters not defined by your function
            schema. Validate the arguments in your code before calling your
            function.
      required:
        - name
        - arguments
    chatCompletionRequestDeveloperMessageContentPart:
      oneOf:
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartText'
    chatCompletionRequestSystemMessageContentPart:
      oneOf:
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartText'
    chatCompletionRequestUserMessageContentPart:
      oneOf:
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartText'
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartImage'
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartAudio'
    chatCompletionRequestAssistantMessageContentPart:
      oneOf:
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartText'
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartRefusal'
    chatCompletionMessageToolCalls:
      type: array
      description: The tool calls generated by the model, such as function calls.
      items:
        oneOf:
          - $ref: '#/components/schemas/chatCompletionMessageToolCall'
          - $ref: '#/components/schemas/chatCompletionMessageCustomToolCall'
    chatCompletionRequestToolMessageContentPart:
      oneOf:
        - $ref: '#/components/schemas/chatCompletionRequestMessageContentPartText'
    toolCallType:
      type: string
      enum:
        - function
      description: The type of the tool call, in this case `function`.
      x-ms-enum:
        name: ToolCallType
        modelAsString: true
        values:
          - value: function
            description: The tool call type is function.
    customToolCallType:
      type: string
      enum:
        - custom
      description: The type of the tool. Always `custom`.
      x-ms-enum:
        name: CustomToolCallType
        modelAsString: true
        values:
          - value: custom
            description: The tool call type is custom.
    chatCompletionRequestMessageContentPartImage:
      type: object
      title: Image content part
      properties:
        type:
          type: string
          enum:
            - image_url
          description: The type of the content part.
        image_url:
          type: object
          properties:
            url:
              type: string
              description: Either a URL of the image or the base64 encoded image data.
              format: uri
            detail:
              type: string
              description: >-
                Specifies the detail level of the image. Learn more in the
                [Vision
                guide](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/gpt-with-vision?tabs=rest%2Csystem-assigned%2Cresource#detail-parameter-settings-in-image-processing-low-high-auto).
              enum:
                - auto
                - low
                - high
              default: auto
          required:
            - url
      required:
        - type
        - image_url
    chatCompletionRequestMessageContentPartAudio:
      type: object
      title: Audio content part
      description: |
        Learn about [audio inputs](/docs/guides/audio).
      properties:
        type:
          type: string
          enum:
            - input_audio
          description: The type of the content part. Always `input_audio`.
        input_audio:
          type: object
          properties:
            data:
              type: string
              description: Base64 encoded audio data.
            format:
              type: string
              enum:
                - wav
                - mp3
              description: >
                The format of the encoded audio data. Currently supports "wav"
                and "mp3".
          required:
            - data
            - format
      required:
        - type
        - input_audio
    chatCompletionRequestMessageContentPartRefusal:
      type: object
      title: Refusal content part
      properties:
        type:
          type: string
          enum:
            - refusal
          description: The type of the content part.
        refusal:
          type: string
          description: The refusal message generated by the model.
      required:
        - type
        - refusal
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Your Hicap API key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.