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

# Chat Completions

> OpenAI-compatible chat completions endpoint (v3).



## OpenAPI

````yaml https://api.edenai.run/v3/docs/openapi.json post /v3/chat/completions
openapi: 3.1.0
info:
  title: Eden AI API V3
  version: 3.0.0
servers:
  - url: https://api.edenai.run
    description: Production server
security: []
paths:
  /v3/chat/completions:
    post:
      tags:
        - Chat
      summary: Chat Completions
      description: OpenAI-compatible chat completions endpoint (v3).
      operationId: chat_completions_v3_chat_completions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LlmCompletionBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - AuthBearer: []
components:
  schemas:
    LlmCompletionBody:
      properties:
        fallbacks:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 3
            - type: 'null'
          title: Fallbacks
          description: >-
            List of fallback model IDs to try if the primary model fails. Models
            are tried in order. Example: ['anthropic/claude-3-opus',
            'openai/gpt-4o']
        router_candidates:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Router Candidates
          description: >-
            List of model candidates for dynamic routing when using
            model='@edenai'. Each entry should be 'provider/model', e.g.
            ['openai/gpt-4o', 'anthropic/claude-3-5-sonnet-20241022']. If not
            provided, defaults to all available models.
        pre_hooks:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Pre Hooks
          description: >-
            List of hooks to run before the LLM provider call. Each entry must
            have an 'action' key and optional 'params'. Example: [{'action':
            'pdf_text_extract', 'params': {'method': 'default'}}]
        post_hooks:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Post Hooks
          description: >-
            List of hooks to run after the LLM provider call. Each entry must
            have an 'action' key and optional 'params'. Example: [{'action':
            'json_heal', 'params': {'json_schema': {...}}}]
        model:
          type: string
          title: Model
          description: The name of the LLM model to use.
        messages:
          items:
            $ref: '#/components/schemas/Message'
          type: array
          title: Messages
          description: The messages to send to the LLM model.
        'n':
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: 'N'
          description: >-
            The number of completions to generate for each prompt. Defaults to
            1.
          default: 1
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - minimal
                - low
                - medium
                - high
                - max
                - xhigh
                - disable
                - none
            - type: 'null'
          title: Reasoning Effort
          description: The reasoning effort level for the LLM model.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Object of metadata associated with the chat request. Can be used to
            provide additional context or tracking information.
        frequency_penalty:
          anyOf:
            - type: number
              maximum: 2
              minimum: -2
            - type: 'null'
          title: Frequency Penalty
          description: Penalty for repeated tokens in the output.
        logit_bias:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Logit Bias
          description: Logit bias to influence token generation.
        logprobs:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Logprobs
          description: >-
            Whether to include log probabilities of tokens in the output.
            Defaults to False.
          default: false
        top_logprobs:
          anyOf:
            - type: integer
              maximum: 20
              minimum: 1
            - type: 'null'
          title: Top Logprobs
          description: Number of top log probabilities to return with each token.
        max_tokens:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Tokens
          description: The maximum number of tokens to generate in the chat completion
        max_completion_tokens:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: 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.
        modalities:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Modalities
          description: List of supported input/output modalities for the chat.
        prediction:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Prediction
          description: field for storing prediction-related information.
        audio:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Audio
          description: dictionary for audio-related parameters or metadata.
        presence_penalty:
          anyOf:
            - type: number
              maximum: 2
              minimum: -2
            - type: 'null'
          title: Presence Penalty
          description: Penalty for new tokens based on their presence in the text so far.
        response_format:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response Format
          description: Specify the desired response format for the completion.
        seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seed
          description: Seed for random number generation.
        service_tier:
          anyOf:
            - type: string
              enum:
                - auto
                - default
                - flex
            - type: 'null'
          title: Service Tier
          description: >-
            'auto': Automatically select appropriate tier

            'default': Use the default service tier

            'flex': 50% cheaper processing with increased latency (OpenAI
            o3/o4-mini)
        stop:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop
          description: List of stop sequences to end the generation.
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stream
          description: Whether to stream the response in real-time. Defaults to False.
          default: false
        stream_options:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Stream Options
          description: Options for streaming responses, such as chunk size or format.
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: Sampling temperature for controlling randomness in output.
        top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Top P
          description: >-
            Nucleus sampling parameter for controlling diversity in output.
            Defaults to 1.0.
          default: 1
        tools:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tools
          description: >-
            List of tools that can be used by the model to assist in generating
            responses.
        tool_choice:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/ToolChoiceFunction'
            - type: 'null'
          title: Tool Choice
          description: >-
            Specify how tools should be used. Can be 'auto', 'required', 'none',
            or an object like {'type': 'function', 'function': {'name':
            'tool_name'}} to force a specific tool.
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
          description: Whether to allow parallel tool calls in the completion.
        user:
          anyOf:
            - type: string
            - type: 'null'
          title: User
          description: User identifier for tracking or personalization purposes.
        function_call:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Function Call
          description: >-
            Function call parameters for invoking specific functions during the
            chat.
        functions:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Functions
          description: >-
            List of functions that can be called by the model to assist in
            generating responses.
        thinking:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Thinking
          description: Parameters related to the model's reasoning or thinking process.
        web_search_options:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Web Search Options
          description: >-
            Options for web search integration. Example: json
            web_search_options={ "search_context_size": "medium" # Options:
            "low", "medium", "high" }
        verbosity:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
            - type: 'null'
          title: Verbosity
          description: >-
            Hint the model to be more or less expansive in its replies. Values:
            "low", "medium", "high". low (gpt5 models)
        extra_body:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extra Body
          description: >-
            Additional parameters to pass in the request body to the provider
            API.
        image_config:
          anyOf:
            - $ref: '#/components/schemas/GeminiImageConfig'
            - type: 'null'
          description: >-
            Image generation configuration for Google Gemini image models (e.g.
            google/gemini-2.5-flash-image).
        extra_headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Extra Headers
          description: Additional HTTP headers to pass to the provider API.
      type: object
      required:
        - model
        - messages
      title: LlmCompletionBody
    ChatCompletionResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the chat completion.
        object:
          type: string
          const: chat.completion
          title: Object
          description: Object type. Always 'chat.completion' for this endpoint.
          default: chat.completion
        created:
          type: integer
          title: Created
          description: Unix timestamp (seconds) when the completion was created.
        model:
          type: string
          title: Model
          description: Model that produced the completion.
        choices:
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
          type: array
          title: Choices
          description: List of completion choices generated for the request.
        usage:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionUsage'
            - type: 'null'
          description: Token usage statistics for the request.
        system_fingerprint:
          anyOf:
            - type: string
            - type: 'null'
          title: System Fingerprint
          description: Backend configuration fingerprint that produced the response.
        service_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Tier
          description: Service tier that processed the request.
      additionalProperties: true
      type: object
      required:
        - id
        - created
        - model
        - choices
      title: ChatCompletionResponse
      description: Response body for POST /chat/completions (non-streaming).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Message:
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - tool
            - developer
          title: Role
          description: The role of the message sender (e.g., 'user', 'assistant').
        content:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/MessageTextContent'
                  - $ref: '#/components/schemas/MessageImageContent'
                  - $ref: '#/components/schemas/MessageFileContent'
              type: array
            - type: 'null'
          title: Content
          description: The content of the message, either text or image.
      additionalProperties: true
      type: object
      required:
        - role
      title: Message
    ToolChoiceFunction:
      properties:
        type:
          type: string
          const: function
          title: Type
        function:
          $ref: '#/components/schemas/ToolChoiceFunctionName'
          description: The function to force the model to call.
      type: object
      required:
        - type
        - function
      title: ToolChoiceFunction
    GeminiImageConfig:
      properties:
        aspect_ratio:
          anyOf:
            - type: string
            - type: 'null'
          title: Aspect Ratio
          description: >-
            Output aspect ratio. Examples: '1:1', '16:9', '9:16', '4:3', '3:4',
            '21:9'. Allowed set varies by model; see Gemini docs.
        image_size:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Size
          description: >-
            Output resolution. Examples: '1K', '2K', '4K'. '512' is valid on
            Gemini 3.1 Flash Image only.
      additionalProperties: false
      type: object
      title: GeminiImageConfig
      description: >-
        Image generation config for Gemini image models
        (google/gemini-2.5-flash-image).


        Values are passed through to Gemini's generationConfig.imageConfig.
        Allowed

        values may vary by model — see

        https://ai.google.dev/gemini-api/docs/image-generation.
    ChatCompletionChoice:
      properties:
        index:
          type: integer
          title: Index
          description: Position of the choice in the list.
        message:
          $ref: '#/components/schemas/ChatCompletionMessage'
          description: Message produced by the model for this choice.
        finish_reason:
          anyOf:
            - type: string
              enum:
                - stop
                - length
                - tool_calls
                - content_filter
                - function_call
            - type: 'null'
          title: Finish Reason
          description: Reason the model stopped generating tokens.
        logprobs:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Logprobs
          description: Log probability information for the choice, if requested.
      additionalProperties: true
      type: object
      required:
        - index
        - message
      title: ChatCompletionChoice
      description: A single choice in a chat completion response.
    ChatCompletionUsage:
      properties:
        prompt_tokens:
          type: integer
          title: Prompt Tokens
          description: Tokens in the prompt.
        completion_tokens:
          type: integer
          title: Completion Tokens
          description: Tokens in the generated completion.
        total_tokens:
          type: integer
          title: Total Tokens
          description: Total tokens consumed by the request.
        prompt_tokens_details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Prompt Tokens Details
          description: Breakdown of prompt tokens (e.g. cached_tokens, audio_tokens).
        completion_tokens_details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Completion Tokens Details
          description: Breakdown of completion tokens (e.g. reasoning_tokens).
      additionalProperties: true
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      title: ChatCompletionUsage
      description: Token usage block returned by the OpenAI-compatible chat completion API.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    MessageTextContent:
      properties:
        type:
          type: string
          const: text
          title: Type
        text:
          type: string
          title: Text
          description: The text content of the message.
      type: object
      required:
        - type
        - text
      title: MessageTextContent
    MessageImageContent:
      properties:
        type:
          type: string
          const: image_url
          title: Type
        image_url:
          $ref: '#/components/schemas/MessageImageUrl'
      type: object
      required:
        - type
        - image_url
      title: MessageImageContent
    MessageFileContent:
      properties:
        type:
          type: string
          const: file
          title: Type
        file:
          anyOf:
            - $ref: '#/components/schemas/MessageFileUrlInput'
            - $ref: '#/components/schemas/MessageFileB64Input'
          title: File
      type: object
      required:
        - type
        - file
      title: MessageFileContent
    ToolChoiceFunctionName:
      properties:
        name:
          type: string
          title: Name
          description: The name of the function to call.
      type: object
      required:
        - name
      title: ToolChoiceFunctionName
    ChatCompletionMessage:
      properties:
        role:
          type: string
          const: assistant
          title: Role
          description: Role of the message author.
          default: assistant
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
          description: Content of the message.
        tool_calls:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tool Calls
          description: Tool calls produced by the model, if any.
        refusal:
          anyOf:
            - type: string
            - type: 'null'
          title: Refusal
          description: Refusal message from the model, if any.
        reasoning_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning Content
          description: Reasoning trace from the model, when supported by the provider.
      additionalProperties: true
      type: object
      title: ChatCompletionMessage
      description: Message returned in a chat completion choice.
    MessageImageUrl:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: MessageImageUrl
    MessageFileUrlInput:
      properties:
        file_id:
          type: string
          title: File Id
          description: >-
            File identifier: either a UUID from /v3/upload endpoint or an
            HTTP(S) URL.
      type: object
      required:
        - file_id
      title: MessageFileUrlInput
    MessageFileB64Input:
      properties:
        file_data:
          type: string
          title: File Data
          description: The file data in base64 format.
      type: object
      required:
        - file_data
      title: MessageFileB64Input
  securitySchemes:
    AuthBearer:
      type: http
      scheme: bearer

````