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

# Create Chat Completion



## OpenAPI

````yaml /development/api-reference/openapi.json post /api/v1/openai/chat/completions
openapi: 3.1.0
info:
  title: Agentstack server
  version: 0.6.3
servers: []
security: []
paths:
  /api/v1/openai/chat/completions:
    post:
      tags:
        - openai
      summary: Create Chat Completion
      operationId: create_chat_completion_api_v1_openai_chat_completions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBasic: []
        - HTTPBearer: []
components:
  schemas:
    ChatCompletionRequest:
      properties:
        messages:
          items:
            anyOf:
              - $ref: '#/components/schemas/ChatCompletionDeveloperMessageParam'
              - $ref: '#/components/schemas/ChatCompletionSystemMessageParam'
              - $ref: '#/components/schemas/ChatCompletionUserMessageParam'
              - $ref: '#/components/schemas/ChatCompletionAssistantMessageParam'
              - $ref: '#/components/schemas/ChatCompletionToolMessageParam'
              - $ref: '#/components/schemas/ChatCompletionFunctionMessageParam'
          type: array
          title: Messages
        model:
          anyOf:
            - type: string
            - type: string
              enum:
                - gpt-5.2
                - gpt-5.2-2025-12-11
                - gpt-5.2-chat-latest
                - gpt-5.2-pro
                - gpt-5.2-pro-2025-12-11
                - gpt-5.1
                - gpt-5.1-2025-11-13
                - gpt-5.1-codex
                - gpt-5.1-mini
                - gpt-5.1-chat-latest
                - gpt-5
                - gpt-5-mini
                - gpt-5-nano
                - gpt-5-2025-08-07
                - gpt-5-mini-2025-08-07
                - gpt-5-nano-2025-08-07
                - gpt-5-chat-latest
                - gpt-4.1
                - gpt-4.1-mini
                - gpt-4.1-nano
                - gpt-4.1-2025-04-14
                - gpt-4.1-mini-2025-04-14
                - gpt-4.1-nano-2025-04-14
                - o4-mini
                - o4-mini-2025-04-16
                - o3
                - o3-2025-04-16
                - o3-mini
                - o3-mini-2025-01-31
                - o1
                - o1-2024-12-17
                - o1-preview
                - o1-preview-2024-09-12
                - o1-mini
                - o1-mini-2024-09-12
                - gpt-4o
                - gpt-4o-2024-11-20
                - gpt-4o-2024-08-06
                - gpt-4o-2024-05-13
                - gpt-4o-audio-preview
                - gpt-4o-audio-preview-2024-10-01
                - gpt-4o-audio-preview-2024-12-17
                - gpt-4o-audio-preview-2025-06-03
                - gpt-4o-mini-audio-preview
                - gpt-4o-mini-audio-preview-2024-12-17
                - gpt-4o-search-preview
                - gpt-4o-mini-search-preview
                - gpt-4o-search-preview-2025-03-11
                - gpt-4o-mini-search-preview-2025-03-11
                - chatgpt-4o-latest
                - codex-mini-latest
                - gpt-4o-mini
                - gpt-4o-mini-2024-07-18
                - gpt-4-turbo
                - gpt-4-turbo-2024-04-09
                - gpt-4-0125-preview
                - gpt-4-turbo-preview
                - gpt-4-1106-preview
                - gpt-4-vision-preview
                - gpt-4
                - gpt-4-0314
                - gpt-4-0613
                - gpt-4-32k
                - gpt-4-32k-0314
                - gpt-4-32k-0613
                - gpt-3.5-turbo
                - gpt-3.5-turbo-16k
                - gpt-3.5-turbo-0301
                - gpt-3.5-turbo-0613
                - gpt-3.5-turbo-1106
                - gpt-3.5-turbo-0125
                - gpt-3.5-turbo-16k-0613
          title: Model
        audio:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionAudioParam'
            - type: 'null'
        frequency_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Frequency Penalty
        function_call:
          anyOf:
            - type: string
              enum:
                - none
                - auto
            - $ref: '#/components/schemas/ChatCompletionFunctionCallOptionParam'
            - type: 'null'
          title: Function Call
        functions:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/openai__types__chat__completion_create_params__Function
              type: array
            - type: 'null'
          title: Functions
        logit_bias:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Logit Bias
        logprobs:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Logprobs
        max_completion_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Completion Tokens
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
        metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Metadata
        modalities:
          anyOf:
            - items:
                type: string
                enum:
                  - text
                  - audio
              type: array
            - type: 'null'
          title: Modalities
        'n':
          anyOf:
            - type: integer
            - type: 'null'
          title: 'N'
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
        prediction:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionPredictionContentParam'
            - type: 'null'
        presence_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Presence Penalty
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
            - type: 'null'
          title: Reasoning Effort
        response_format:
          anyOf:
            - $ref: '#/components/schemas/ResponseFormatText'
            - $ref: '#/components/schemas/ResponseFormatJSONSchema'
            - $ref: '#/components/schemas/ResponseFormatJSONObject'
            - type: 'null'
          title: Response Format
        seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seed
        service_tier:
          anyOf:
            - type: string
              enum:
                - auto
                - default
                - flex
                - scale
                - priority
            - type: 'null'
          title: Service Tier
        stop:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop
        store:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Store
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stream
        stream_options:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionStreamOptionsParam'
            - type: 'null'
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        tool_choice:
          anyOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - $ref: '#/components/schemas/ChatCompletionAllowedToolChoiceParam'
            - $ref: '#/components/schemas/ChatCompletionNamedToolChoiceParam'
            - $ref: '#/components/schemas/ChatCompletionNamedToolChoiceCustomParam'
            - type: 'null'
          title: Tool Choice
        tools:
          anyOf:
            - items:
                $ref: '#/components/schemas/ChatCompletionFunctionToolParam'
              type: array
            - type: 'null'
          title: Tools
        top_logprobs:
          anyOf:
            - type: integer
            - type: 'null'
          title: Top Logprobs
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
        user:
          anyOf:
            - type: string
            - type: 'null'
          title: User
        web_search_options:
          anyOf:
            - $ref: '#/components/schemas/WebSearchOptions'
            - type: 'null'
      type: object
      required:
        - messages
        - model
      title: ChatCompletionRequest
      description: Corresponds to args to OpenAI `client.chat.completions.create(...)`
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChatCompletionDeveloperMessageParam:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
              type: array
          title: Content
        role:
          type: string
          const: developer
          title: Role
        name:
          type: string
          title: Name
      type: object
      required:
        - content
        - role
      title: ChatCompletionDeveloperMessageParam
      description: >-
        Developer-provided instructions that the model should follow, regardless
        of

        messages sent by the user. With o1 models and newer, `developer`
        messages

        replace the previous `system` messages.
    ChatCompletionSystemMessageParam:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
              type: array
          title: Content
        role:
          type: string
          const: system
          title: Role
        name:
          type: string
          title: Name
      type: object
      required:
        - content
        - role
      title: ChatCompletionSystemMessageParam
      description: >-
        Developer-provided instructions that the model should follow, regardless
        of

        messages sent by the user. With o1 models and newer, use `developer`
        messages

        for this purpose instead.
    ChatCompletionUserMessageParam:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
                  - $ref: '#/components/schemas/ChatCompletionContentPartImageParam'
                  - $ref: >-
                      #/components/schemas/ChatCompletionContentPartInputAudioParam
                  - $ref: '#/components/schemas/File-Input'
              type: array
          title: Content
        role:
          type: string
          const: user
          title: Role
        name:
          type: string
          title: Name
      type: object
      required:
        - content
        - role
      title: ChatCompletionUserMessageParam
      description: |-
        Messages sent by an end user, containing prompts or additional context
        information.
    ChatCompletionAssistantMessageParam:
      properties:
        role:
          type: string
          const: assistant
          title: Role
        audio:
          anyOf:
            - $ref: '#/components/schemas/Audio'
            - type: 'null'
        content:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
                  - $ref: '#/components/schemas/ChatCompletionContentPartRefusalParam'
              type: array
            - type: 'null'
          title: Content
        function_call:
          anyOf:
            - $ref: '#/components/schemas/FunctionCall'
            - type: 'null'
        name:
          type: string
          title: Name
        refusal:
          anyOf:
            - type: string
            - type: 'null'
          title: Refusal
        tool_calls:
          items:
            anyOf:
              - $ref: >-
                  #/components/schemas/ChatCompletionMessageFunctionToolCallParam
              - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCallParam'
          type: array
          title: Tool Calls
      type: object
      required:
        - role
      title: ChatCompletionAssistantMessageParam
      description: Messages sent by the model in response to user messages.
    ChatCompletionToolMessageParam:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
              type: array
          title: Content
        role:
          type: string
          const: tool
          title: Role
        tool_call_id:
          type: string
          title: Tool Call Id
      type: object
      required:
        - content
        - role
        - tool_call_id
      title: ChatCompletionToolMessageParam
    ChatCompletionFunctionMessageParam:
      properties:
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
        name:
          type: string
          title: Name
        role:
          type: string
          const: function
          title: Role
      type: object
      required:
        - content
        - name
        - role
      title: ChatCompletionFunctionMessageParam
    ChatCompletionAudioParam:
      properties:
        format:
          type: string
          enum:
            - wav
            - aac
            - mp3
            - flac
            - opus
            - pcm16
          title: Format
        voice:
          anyOf:
            - type: string
            - type: string
              enum:
                - alloy
                - ash
                - ballad
                - coral
                - echo
                - sage
                - shimmer
                - verse
                - marin
                - cedar
          title: Voice
      type: object
      required:
        - format
        - voice
      title: ChatCompletionAudioParam
      description: >-
        Parameters for audio output.


        Required when audio output is requested with

        `modalities: ["audio"]`. [Learn
        more](https://platform.openai.com/docs/guides/audio).
    ChatCompletionFunctionCallOptionParam:
      properties:
        name:
          type: string
          title: Name
      type: object
      required:
        - name
      title: ChatCompletionFunctionCallOptionParam
      description: >-
        Specifying a particular function via `{"name": "my_function"}` forces
        the model to call that function.
    openai__types__chat__completion_create_params__Function:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
      type: object
      required:
        - name
      title: Function
    ChatCompletionPredictionContentParam:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
              type: array
          title: Content
        type:
          type: string
          const: content
          title: Type
      type: object
      required:
        - content
        - type
      title: ChatCompletionPredictionContentParam
      description: >-
        Static predicted output content, such as the content of a text file that
        is

        being regenerated.
    ResponseFormatText:
      properties:
        type:
          type: string
          const: text
          title: Type
      type: object
      required:
        - type
      title: ResponseFormatText
      description: Default response format. Used to generate text responses.
    ResponseFormatJSONSchema:
      properties:
        json_schema:
          $ref: '#/components/schemas/JSONSchema'
        type:
          type: string
          const: json_schema
          title: Type
      type: object
      required:
        - json_schema
        - type
      title: ResponseFormatJSONSchema
      description: >-
        JSON Schema response format.


        Used to generate structured JSON responses.

        Learn more about [Structured
        Outputs](https://platform.openai.com/docs/guides/structured-outputs).
    ResponseFormatJSONObject:
      properties:
        type:
          type: string
          const: json_object
          title: Type
      type: object
      required:
        - type
      title: ResponseFormatJSONObject
      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.
    ChatCompletionStreamOptionsParam:
      properties:
        include_obfuscation:
          type: boolean
          title: Include Obfuscation
        include_usage:
          type: boolean
          title: Include Usage
      type: object
      title: ChatCompletionStreamOptionsParam
      description: >-
        Options for streaming response. Only set this when you set `stream:
        true`.
    ChatCompletionAllowedToolChoiceParam:
      properties:
        allowed_tools:
          $ref: '#/components/schemas/ChatCompletionAllowedToolsParam'
        type:
          type: string
          const: allowed_tools
          title: Type
      type: object
      required:
        - allowed_tools
        - type
      title: ChatCompletionAllowedToolChoiceParam
      description: Constrains the tools available to the model to a pre-defined set.
    ChatCompletionNamedToolChoiceParam:
      properties:
        function:
          $ref: >-
            #/components/schemas/openai__types__chat__chat_completion_named_tool_choice_param__Function
        type:
          type: string
          const: function
          title: Type
      type: object
      required:
        - function
        - type
      title: ChatCompletionNamedToolChoiceParam
      description: |-
        Specifies a tool the model should use.

        Use to force the model to call a specific function.
    ChatCompletionNamedToolChoiceCustomParam:
      properties:
        custom:
          $ref: >-
            #/components/schemas/openai__types__chat__chat_completion_named_tool_choice_custom_param__Custom
        type:
          type: string
          const: custom
          title: Type
      type: object
      required:
        - custom
        - type
      title: ChatCompletionNamedToolChoiceCustomParam
      description: |-
        Specifies a tool the model should use.

        Use to force the model to call a specific custom tool.
    ChatCompletionFunctionToolParam:
      properties:
        function:
          $ref: '#/components/schemas/FunctionDefinition'
        type:
          type: string
          const: function
          title: Type
      type: object
      required:
        - function
        - type
      title: ChatCompletionFunctionToolParam
      description: A function tool that can be used to generate a response.
    WebSearchOptions:
      properties:
        search_context_size:
          type: string
          enum:
            - low
            - medium
            - high
          title: Search Context Size
        user_location:
          anyOf:
            - $ref: '#/components/schemas/WebSearchOptionsUserLocation'
            - type: 'null'
      type: object
      title: WebSearchOptions
      description: >-
        This tool searches the web for relevant results to use in a response.

        Learn more about the [web search
        tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ChatCompletionContentPartTextParam:
      properties:
        text:
          type: string
          title: Text
        type:
          type: string
          const: text
          title: Type
      type: object
      required:
        - text
        - type
      title: ChatCompletionContentPartTextParam
      description: >-
        Learn about [text
        inputs](https://platform.openai.com/docs/guides/text-generation).
    ChatCompletionContentPartImageParam:
      properties:
        image_url:
          $ref: '#/components/schemas/ImageURL'
        type:
          type: string
          const: image_url
          title: Type
      type: object
      required:
        - image_url
        - type
      title: ChatCompletionContentPartImageParam
      description: >-
        Learn about [image
        inputs](https://platform.openai.com/docs/guides/vision).
    ChatCompletionContentPartInputAudioParam:
      properties:
        input_audio:
          $ref: '#/components/schemas/InputAudio'
        type:
          type: string
          const: input_audio
          title: Type
      type: object
      required:
        - input_audio
        - type
      title: ChatCompletionContentPartInputAudioParam
      description: >-
        Learn about [audio
        inputs](https://platform.openai.com/docs/guides/audio).
    File-Input:
      properties:
        file:
          $ref: '#/components/schemas/FileFile'
        type:
          type: string
          const: file
          title: Type
      type: object
      required:
        - file
        - type
      title: File
      description: >-
        Learn about [file inputs](https://platform.openai.com/docs/guides/text)
        for text generation.
    Audio:
      properties:
        id:
          type: string
          title: Id
      type: object
      required:
        - id
      title: Audio
      description: |-
        Data about a previous audio response from the model.
        [Learn more](https://platform.openai.com/docs/guides/audio).
    ChatCompletionContentPartRefusalParam:
      properties:
        refusal:
          type: string
          title: Refusal
        type:
          type: string
          const: refusal
          title: Type
      type: object
      required:
        - refusal
        - type
      title: ChatCompletionContentPartRefusalParam
    FunctionCall:
      properties:
        arguments:
          type: string
          title: Arguments
        name:
          type: string
          title: Name
      type: object
      required:
        - arguments
        - name
      title: FunctionCall
      description: >-
        Deprecated and replaced by `tool_calls`.


        The name and arguments of a function that should be called, as generated
        by the model.
    ChatCompletionMessageFunctionToolCallParam:
      properties:
        id:
          type: string
          title: Id
        function:
          $ref: >-
            #/components/schemas/openai__types__chat__chat_completion_message_function_tool_call_param__Function
        type:
          type: string
          const: function
          title: Type
      type: object
      required:
        - id
        - function
        - type
      title: ChatCompletionMessageFunctionToolCallParam
      description: A call to a function tool created by the model.
    ChatCompletionMessageCustomToolCallParam:
      properties:
        id:
          type: string
          title: Id
        custom:
          $ref: >-
            #/components/schemas/openai__types__chat__chat_completion_message_custom_tool_call_param__Custom
        type:
          type: string
          const: custom
          title: Type
      type: object
      required:
        - id
        - custom
        - type
      title: ChatCompletionMessageCustomToolCallParam
      description: A call to a custom tool created by the model.
    JSONSchema:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        schema:
          additionalProperties: true
          type: object
          title: Schema
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
      type: object
      required:
        - name
      title: JSONSchema
      description: Structured Outputs configuration options, including a JSON Schema.
    ChatCompletionAllowedToolsParam:
      properties:
        mode:
          type: string
          enum:
            - auto
            - required
          title: Mode
        tools:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Tools
      type: object
      required:
        - mode
        - tools
      title: ChatCompletionAllowedToolsParam
      description: Constrains the tools available to the model to a pre-defined set.
    openai__types__chat__chat_completion_named_tool_choice_param__Function:
      properties:
        name:
          type: string
          title: Name
      type: object
      required:
        - name
      title: Function
    openai__types__chat__chat_completion_named_tool_choice_custom_param__Custom:
      properties:
        name:
          type: string
          title: Name
      type: object
      required:
        - name
      title: Custom
    FunctionDefinition:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Strict
      type: object
      required:
        - name
      title: FunctionDefinition
    WebSearchOptionsUserLocation:
      properties:
        approximate:
          $ref: '#/components/schemas/WebSearchOptionsUserLocationApproximate'
        type:
          type: string
          const: approximate
          title: Type
      type: object
      required:
        - approximate
        - type
      title: WebSearchOptionsUserLocation
      description: Approximate location parameters for the search.
    ImageURL:
      properties:
        url:
          type: string
          title: Url
        detail:
          type: string
          enum:
            - auto
            - low
            - high
          title: Detail
      type: object
      required:
        - url
      title: ImageURL
    InputAudio:
      properties:
        data:
          type: string
          title: Data
        format:
          type: string
          enum:
            - wav
            - mp3
          title: Format
      type: object
      required:
        - data
        - format
      title: InputAudio
    FileFile:
      properties:
        file_data:
          type: string
          title: File Data
        file_id:
          type: string
          title: File Id
        filename:
          type: string
          title: Filename
      type: object
      title: FileFile
    openai__types__chat__chat_completion_message_function_tool_call_param__Function:
      properties:
        arguments:
          type: string
          title: Arguments
        name:
          type: string
          title: Name
      type: object
      required:
        - arguments
        - name
      title: Function
      description: The function that the model called.
    openai__types__chat__chat_completion_message_custom_tool_call_param__Custom:
      properties:
        input:
          type: string
          title: Input
        name:
          type: string
          title: Name
      type: object
      required:
        - input
        - name
      title: Custom
      description: The custom tool that the model called.
    WebSearchOptionsUserLocationApproximate:
      properties:
        city:
          type: string
          title: City
        country:
          type: string
          title: Country
        region:
          type: string
          title: Region
        timezone:
          type: string
          title: Timezone
      type: object
      title: WebSearchOptionsUserLocationApproximate
      description: Approximate location parameters for the search.
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic
    HTTPBearer:
      type: http
      scheme: bearer

````