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

# Create a chat completion

> Request a chat completion. Supports `tools` and `tool_choice` for function calling, and `reasoning_effort` for reasoning models. Body follows ChatCompletionsRequest.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/chat/completions
openapi: 3.1.0
info:
  title: SynapsAI Inference API
  version: 1.0.0
servers:
  - url: https://api.synapsai.cloud
    description: Production server
security: []
paths:
  /v1/chat/completions:
    post:
      summary: Create a chat completion
      description: >-
        Request a chat completion. Supports `tools` and `tool_choice` for
        function calling, and `reasoning_effort` for reasoning models. Body
        follows ChatCompletionsRequest.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionsRequest'
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsResponse'
components:
  schemas:
    ChatCompletionsRequest:
      allOf:
        - type: object
          description: >-
            Request body for chat completions endpoint describing conversation
            and generation parameters.
          properties:
            messages:
              type: array
              items:
                type: object
                additionalProperties: true
              description: >-
                List of messages (role + content) forming the chat history.
                Required.
            temperature:
              type: number
              nullable: true
              description: Sampling temperature; higher values increase randomness.
            top_p:
              type: number
              nullable: true
              description: Nucleus sampling cumulative probability threshold.
            top_k:
              type: integer
              nullable: true
              description: >-
                Keep only the top_k tokens by probability at each generation
                step.
            max_completion_tokens:
              type: integer
              nullable: true
              description: >-
                Maximum number of tokens the model may generate for the
                completion.
            stream:
              type: boolean
              default: false
              description: >-
                If true, the server may stream partial responses as they are
                generated.
            frequency_penalty:
              type: number
              nullable: true
              description: >-
                Penalty applied based on frequency of tokens to reduce
                repetition.
            presence_penalty:
              type: number
              nullable: true
              description: >-
                Penalty applied to discourage new token presence (encourages
                topic shifting).
            logit_bias:
              type: object
              additionalProperties:
                type: number
              nullable: true
              description: >-
                Mapping from token id (string or int) to a bias value added to
                the token logits.
            logprobs:
              type: boolean
              default: false
              description: If true, include logprob information in the response.
            top_logprobs:
              type: integer
              nullable: true
              description: >-
                Return the top N token logprobs at each position if logprobs
                enabled.
            stop:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
              nullable: true
              description: Stop sequence or list of sequences where generation should halt.
            seed:
              type: integer
              nullable: true
              description: Optional random seed for reproducibility.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/Tool'
              nullable: true
              description: >-
                Optional list of tool/function definitions that the model may
                call.
            tool_choice:
              $ref: '#/components/schemas/ToolChoice'
              nullable: true
              description: >-
                Controls which tool the model calls: `auto`, `none`, `required`,
                or a specific function.
            reasoning_effort:
              $ref: '#/components/schemas/ReasoningEffort'
              nullable: true
              description: >-
                Constrains reasoning depth for supported reasoning models.
                Higher values generally increase quality and latency.
          required:
            - messages
    ChatCompletionsResponse:
      type: object
      description: Response schema for the chat completions endpoint.
      properties:
        id:
          type: string
          description: Unique identifier for this chat completion.
        object:
          type: string
          default: chat.completion
          description: Type of the returned object; defaults to 'chat.completion'.
        created:
          type: integer
          description: Unix timestamp (seconds) of creation.
        model:
          type: string
          description: Model identifier used to generate the chat response.
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatChoice'
          description: List of chat choices returned by the model.
        usage:
          $ref: '#/components/schemas/ChatUsage'
          description: Token usage details for the chat completion.
      required:
        - id
        - object
        - created
        - model
        - choices
        - usage
    Tool:
      type: object
      description: Wrapper that indicates a function tool available to the model.
      properties:
        type:
          type: string
          enum:
            - function
          default: function
          description: Type of this Tool object; currently always 'function'.
        function:
          $ref: '#/components/schemas/Function'
          description: The function definition exposed by this tool.
    ToolChoice:
      oneOf:
        - type: string
          enum:
            - auto
            - none
            - required
          description: >-
            Tool selection mode: let the model decide (`auto`), disable tools
            (`none`), or require a tool call (`required`).
        - type: object
          properties:
            type:
              type: string
              enum:
                - function
              description: Indicates a specific function must be called.
            function:
              $ref: '#/components/schemas/ToolChoiceFunction'
              description: The function the model must call.
          required:
            - type
            - function
      description: Controls which (if any) tool the model should call.
    ReasoningEffort:
      type: string
      enum:
        - none
        - minimal
        - low
        - medium
        - high
        - xhigh
      description: >-
        Constrains how much internal reasoning the model performs before
        responding. Supported values depend on the model.
    ChatChoice:
      type: object
      description: A single choice in a chat completion response.
      properties:
        index:
          type: integer
          description: Index position of this chat choice.
        message:
          $ref: '#/components/schemas/ChoiceMessage'
          description: Message object produced for this choice.
        logprobs:
          $ref: '#/components/schemas/Logprobs'
          nullable: true
          description: Optional token logprob information for the choice message.
        finish_reason:
          type: string
          enum:
            - stop
            - length
            - tool_calls
          default: stop
          description: >-
            Why generation ended for this choice (e.g., 'stop', 'length',
            'tool_calls').
    ChatUsage:
      type: object
      description: Token usage counts for chat completions.
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens consumed by the input messages.
        completion_tokens:
          type: integer
          description: Number of tokens generated by the assistant in the response.
        total_tokens:
          type: integer
          description: Total tokens consumed for the chat request.
    Function:
      type: object
      description: >-
        Definition of an external function/tool that can be called by the
        system.
      properties:
        name:
          type: string
          description: Canonical name of the function.
        description:
          type: string
          description: Human-readable description of what this function does.
        parameters:
          type: object
          additionalProperties: true
          description: >-
            JSON Schema-like description of function parameters; allows
            arbitrary keys and nested definitions.
      required:
        - name
        - description
        - parameters
    ToolChoiceFunction:
      type: object
      description: Force the model to call a specific function.
      properties:
        name:
          type: string
          description: Name of the function the model must call.
      required:
        - name
    ChoiceMessage:
      type: object
      description: Message shape returned inside a ChatChoice, can be plain or structured.
      properties:
        role:
          type: string
          description: Role associated with the choice message (e.g., 'assistant').
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties:
                  type: string
          nullable: true
          description: >-
            Content of the choice: either a single string or a list of small
            key/value parts. May be null when the model returns tool calls
            instead.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
          nullable: true
          description: Tool calls parsed from the model response, when available.
    Logprobs:
      type: object
      description: Collection of token-level logprob entries for an output.
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/LogprobContent'
          description: List of per-token logprob data.
    ToolCall:
      type: object
      description: A tool call requested by the model in a chat completion response.
      properties:
        id:
          type: string
          description: Unique identifier for this tool call.
        type:
          type: string
          enum:
            - function
          default: function
          description: Type of tool call; currently always 'function'.
        function:
          $ref: '#/components/schemas/ToolCallFunction'
          description: The function to invoke and its arguments.
      required:
        - id
        - type
        - function
    LogprobContent:
      type: object
      description: A single token's log probability information.
      properties:
        token:
          type: string
          description: The token string.
        logprob:
          type: number
          description: Log probability for the token.
        top_logprobs:
          type: object
          additionalProperties: true
          nullable: true
          description: Optional mapping of top tokens to their logprobs for this position.
    ToolCallFunction:
      type: object
      description: Function invocation details inside a tool call.
      properties:
        name:
          type: string
          description: Name of the function the model wants to call.
        arguments:
          type: string
          description: JSON-encoded arguments for the function call.
      required:
        - name
        - arguments

````