Beatra AI Chat Completions API

openapi: 3.2.0
info:
  title: agent_service (api) Chat API
  version: 0.1.0
tags:
- name: Chat Completions
paths:
  /v1/chat/completions:
    post:
      tags:
      - Chat Completions
      summary: Create chat completion (OpenAI-compatible)
      description: Creates a chat completion using an OpenAI-compatible request and response shape. Set `stream=true` to receive Server-Sent Events with `chat.completion.chunk` payloads. Use `model="auto"` to let beatra choose a capable model, or pass a specific model id returned by `/v1/models`.
      operationId: chat_completions_v1_chat_completions_post
      parameters:
      - name: x-request-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Request-Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Sync completion or streaming chat completion chunks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events: `data: <ChatCompletionChunk>` events followed by `data: [DONE]`.'
        '402':
          description: Account balance too low
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '502':
          description: Model request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Model temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-beatra:
        visibility: internal
        group: chat
        title: Text generation
        product_area: Text generation
        mode: sync
        lifecycle: ga
        release_state: ga
        customer_facing: true
        docs_order: 10
components:
  schemas:
    Logprobs:
      properties:
        content:
          anyOf:
          - items:
              $ref: '#/components/schemas/LogprobToken'
            type: array
          - type: 'null'
          title: Content
        refusal:
          anyOf:
          - items:
              $ref: '#/components/schemas/LogprobToken'
            type: array
          - type: 'null'
          title: Refusal
      type: object
      title: Logprobs
    ChatCompletionResponse:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: chat.completion
          title: Object
          default: chat.completion
        created:
          type: integer
          title: Created
        model:
          type: string
          title: Model
          description: Resolved model snapshot (OpenAI convention)
        system_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: System Fingerprint
        service_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Tier
        choices:
          items:
            $ref: '#/components/schemas/ChatChoice'
          type: array
          title: Choices
        usage:
          $ref: '#/components/schemas/ChatUsage'
      type: object
      required:
      - id
      - created
      - model
      - choices
      - usage
      title: ChatCompletionResponse
      description: Standard OpenAI ChatCompletion response plus usage.credits.
    ChatChoice:
      properties:
        index:
          type: integer
          title: Index
        message:
          $ref: '#/components/schemas/AssistantMessage'
        finish_reason:
          anyOf:
          - type: string
            enum:
            - stop
            - length
            - tool_calls
            - content_filter
            - function_call
          - type: 'null'
          title: Finish Reason
        logprobs:
          anyOf:
          - $ref: '#/components/schemas/Logprobs'
          - type: 'null'
      type: object
      required:
      - index
      - message
      - finish_reason
      title: ChatChoice
    ChatUsage:
      properties:
        prompt_tokens:
          type: integer
          title: Prompt Tokens
        completion_tokens:
          type: integer
          title: Completion Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        cache_creation_input_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Creation Input Tokens
        cache_read_input_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Read Input Tokens
        reasoning_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reasoning Tokens
        prompt_tokens_details:
          anyOf:
          - $ref: '#/components/schemas/PromptTokensDetails'
          - type: 'null'
        completion_tokens_details:
          anyOf:
          - $ref: '#/components/schemas/CompletionTokensDetails'
          - type: 'null'
        credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Credits
          description: Credits charged for this call. Populated by PR-2.
      type: object
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
      title: ChatUsage
    ResponseFormatJsonSchema:
      properties:
        type:
          type: string
          const: json_schema
          title: Type
          default: json_schema
        json_schema:
          $ref: '#/components/schemas/JsonSchemaDef'
      type: object
      required:
      - json_schema
      title: ResponseFormatJsonSchema
    ImageUrlData:
      properties:
        url:
          type: string
          title: Url
        detail:
          anyOf:
          - type: string
            enum:
            - auto
            - low
            - default
            - high
          - type: 'null'
          title: Detail
          default: auto
        max_long_side_pixel:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Long Side Pixel
      type: object
      required:
      - url
      title: ImageUrlData
    InputAudioContentPart:
      properties:
        type:
          type: string
          const: input_audio
          title: Type
        input_audio:
          $ref: '#/components/schemas/InputAudioData'
      type: object
      required:
      - type
      - input_audio
      title: InputAudioContentPart
    ReasoningConfig:
      properties:
        effort:
          anyOf:
          - type: string
            enum:
            - minimal
            - low
            - medium
            - high
            - max
          - type: 'null'
          title: Effort
        mode:
          anyOf:
          - type: string
            enum:
            - fixed
            - adaptive
          - type: 'null'
          title: Mode
        expose_trace:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Expose Trace
          description: Return the reasoning trace separately (maps to MiniMax reasoning_split).
      additionalProperties: false
      type: object
      title: ReasoningConfig
      description: 'Model-agnostic reasoning controls.


        The object form of the `reasoning` field. The bare booleans are sugar:

        `reasoning: true` == `{}` (on at the model default), `reasoning: false`

        == reasoning off. Engine-specific wire differences (DeepSeek `enabled`,

        MiniMax `adaptive`, NVIDIA `chat_template_kwargs`) are translated

        server-side.'
    ToolMessage:
      properties:
        role:
          type: string
          const: tool
          title: Role
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/TextContentPart'
            type: array
          title: Content
        tool_call_id:
          type: string
          title: Tool Call Id
      type: object
      required:
      - role
      - content
      - tool_call_id
      title: ToolMessage
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable public error code
        type:
          type: string
          title: Type
          description: Broad SDK-friendly error family
        message:
          type: string
          title: Message
          description: Human-readable explanation
        retryable:
          type: boolean
          title: Retryable
          description: If true, retrying the exact same request may succeed
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Code-specific structured info
        request_id:
          type: string
          title: Request Id
          description: Echo of X-Request-Id for support correlation
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
          description: JSON Pointer to offending field, if applicable
      type: object
      required:
      - code
      - type
      - message
      - retryable
      - request_id
      title: ErrorBody
    LogprobToken:
      properties:
        token:
          type: string
          title: Token
        logprob:
          type: number
          title: Logprob
        bytes:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Bytes
        top_logprobs:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Top Logprobs
      type: object
      required:
      - token
      - logprob
      title: LogprobToken
    FileContentPart:
      properties:
        type:
          type: string
          const: file
          title: Type
        file:
          $ref: '#/components/schemas/FileData'
      type: object
      required:
      - type
      - file
      title: FileContentPart
    StreamOptions:
      properties:
        include_usage:
          type: boolean
          title: Include Usage
          default: false
      type: object
      title: StreamOptions
    Tool:
      properties:
        type:
          type: string
          const: function
          title: Type
          default: function
        function:
          $ref: '#/components/schemas/FunctionDefinition'
      type: object
      required:
      - function
      title: Tool
    PromptTokensDetails:
      properties:
        cached_tokens:
          type: integer
          title: Cached Tokens
          default: 0
        audio_tokens:
          type: integer
          title: Audio Tokens
          default: 0
      type: object
      title: PromptTokensDetails
    VideoUrlContentPart:
      properties:
        type:
          type: string
          const: video_url
          title: Type
        video_url:
          $ref: '#/components/schemas/VideoUrlData'
      type: object
      required:
      - type
      - video_url
      title: VideoUrlContentPart
    AssistantAudio:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
        expires_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Expires At
        transcript:
          anyOf:
          - type: string
          - type: 'null'
          title: Transcript
      type: object
      title: AssistantAudio
    InputAudioData:
      properties:
        data:
          type: string
          title: Data
          description: base64-encoded audio bytes
        format:
          type: string
          enum:
          - wav
          - mp3
          title: Format
      type: object
      required:
      - data
      - format
      title: InputAudioData
    ToolCall:
      properties:
        id:
          type: string
          title: Id
        type:
          type: string
          const: function
          title: Type
          default: function
        function:
          $ref: '#/components/schemas/ToolCallFunction'
      type: object
      required:
      - id
      - function
      title: ToolCall
    ImageUrlContentPart:
      properties:
        type:
          type: string
          const: image_url
          title: Type
        image_url:
          $ref: '#/components/schemas/ImageUrlData'
      type: object
      required:
      - type
      - image_url
      title: ImageUrlContentPart
    SystemMessage:
      properties:
        role:
          type: string
          enum:
          - system
          - developer
          title: Role
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/TextContentPart'
            type: array
          title: Content
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      type: object
      required:
      - role
      - content
      title: SystemMessage
    ResponseFormatText:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
      type: object
      title: ResponseFormatText
    UserMessage:
      properties:
        role:
          type: string
          const: user
          title: Role
        content:
          anyOf:
          - type: string
          - items:
              oneOf:
              - $ref: '#/components/schemas/TextContentPart'
              - $ref: '#/components/schemas/ImageUrlContentPart'
              - $ref: '#/components/schemas/VideoUrlContentPart'
              - $ref: '#/components/schemas/InputAudioContentPart'
              - $ref: '#/components/schemas/FileContentPart'
              discriminator:
                propertyName: type
                mapping:
                  file: '#/components/schemas/FileContentPart'
                  image_url: '#/components/schemas/ImageUrlContentPart'
                  input_audio: '#/components/schemas/InputAudioContentPart'
                  text: '#/components/schemas/TextContentPart'
                  video_url: '#/components/schemas/VideoUrlContentPart'
            type: array
          title: Content
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      type: object
      required:
      - role
      - content
      title: UserMessage
    ChatCompletionRequest:
      properties:
        model:
          type: string
          title: Model
          description: Model name (e.g. 'gpt-4o-mini', 'qwen-max', 'auto')
        messages:
          items:
            oneOf:
            - $ref: '#/components/schemas/SystemMessage'
            - $ref: '#/components/schemas/UserMessage'
            - $ref: '#/components/schemas/AssistantMessage'
            - $ref: '#/components/schemas/ToolMessage'
            discriminator:
              propertyName: role
              mapping:
                assistant: '#/components/schemas/AssistantMessage'
                developer: '#/components/schemas/SystemMessage'
                system: '#/components/schemas/SystemMessage'
                tool: '#/components/schemas/ToolMessage'
                user: '#/components/schemas/UserMessage'
          type: array
          title: Messages
        temperature:
          anyOf:
          - type: number
            maximum: 2.0
            minimum: 0.0
          - type: 'null'
          title: Temperature
        top_p:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Top P
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          description: Legacy; reasoning models reject this. beatra maps to max_completion_tokens.
        max_completion_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Completion Tokens
        n:
          anyOf:
          - type: integer
            maximum: 10.0
            minimum: 1.0
          - type: 'null'
          title: N
        seed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seed
        stop:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - type: 'null'
          title: Stop
        stream:
          type: boolean
          title: Stream
          default: false
        stream_options:
          anyOf:
          - $ref: '#/components/schemas/StreamOptions'
          - type: 'null'
        frequency_penalty:
          anyOf:
          - type: number
            maximum: 2.0
            minimum: -2.0
          - type: 'null'
          title: Frequency Penalty
        presence_penalty:
          anyOf:
          - type: number
            maximum: 2.0
            minimum: -2.0
          - type: 'null'
          title: Presence Penalty
        logit_bias:
          anyOf:
          - additionalProperties:
              type: number
            type: object
          - type: 'null'
          title: Logit Bias
        logprobs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Logprobs
        top_logprobs:
          anyOf:
          - type: integer
            maximum: 20.0
            minimum: 0.0
          - type: 'null'
          title: Top Logprobs
        tools:
          anyOf:
          - items:
              $ref: '#/components/schemas/Tool'
            type: array
          - type: 'null'
          title: Tools
        tool_choice:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/NamedFunctionChoice'
          - type: 'null'
          title: Tool Choice
        parallel_tool_calls:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Parallel Tool Calls
        response_format:
          anyOf:
          - oneOf:
            - $ref: '#/components/schemas/ResponseFormatText'
            - $ref: '#/components/schemas/ResponseFormatJsonObject'
            - $ref: '#/components/schemas/ResponseFormatJsonSchema'
            discriminator:
              propertyName: type
              mapping:
                json_object: '#/components/schemas/ResponseFormatJsonObject'
                json_schema: '#/components/schemas/ResponseFormatJsonSchema'
                text: '#/components/schemas/ResponseFormatText'
          - type: 'null'
          title: Response Format
        reasoning:
          anyOf:
          - type: boolean
          - $ref: '#/components/schemas/ReasoningConfig'
          - type: 'null'
          title: Reasoning
        reasoning_effort:
          anyOf:
          - type: string
            enum:
            - minimal
            - low
            - medium
            - high
            - max
            - xhigh
          - type: 'null'
          title: Reasoning Effort
        audio:
          anyOf:
          - $ref: '#/components/schemas/AudioOutputConfig'
          - type: 'null'
        modalities:
          anyOf:
          - items:
              type: string
              enum:
              - text
              - audio
            type: array
          - type: 'null'
          title: Modalities
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Metadata
        store:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Store
        service_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Tier
        safety_identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Safety Identifier
        prompt_cache_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Cache Key
        user:
          anyOf:
          - type: string
          - type: 'null'
          title: User
          description: Deprecated; use safety_identifier
      additionalProperties: false
      type: object
      required:
      - model
      - messages
      title: ChatCompletionRequest
      description: 'Request body for POST /v1/chat/completions.


        OpenAI-compatible request with an explicit, typed field surface. Raw

        upstream passthrough is intentionally forbidden because it can override

        the routed model, messages, streaming mode, or operator service tier.'
    VideoUrlData:
      properties:
        url:
          type: string
          title: Url
        detail:
          anyOf:
          - type: string
            enum:
            - auto
            - low
            - default
            - high
          - type: 'null'
          title: Detail
          default: auto
        fps:
          anyOf:
          - type: number
            maximum: 5.0
            minimum: 0.2
          - type: 'null'
          title: Fps
        max_frames:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Frames
        max_long_side_pixel:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Long Side Pixel
      type: object
      required:
      - url
      title: VideoUrlData
    ResponseFormatJsonObject:
      properties:
        type:
          type: string
          const: json_object
          title: Type
          default: json_object
      type: object
      title: ResponseFormatJsonObject
    AudioOutputConfig:
      properties:
        voice:
          type: string
          title: Voice
        format:
          type: string
          enum:
          - wav
          - mp3
          - flac
          - opus
          - pcm16
          title: Format
      type: object
      required:
      - voice
      - format
      title: AudioOutputConfig
    AssistantMessage:
      properties:
        role:
          type: string
          const: assistant
          title: Role
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/TextContentPart'
            type: array
          - type: 'null'
          title: Content
        refusal:
          anyOf:
          - type: string
          - type: 'null'
          title: Refusal
        reasoning_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning Content
          description: Chain-of-thought from thinking models (DeepSeek-Reasoner / GLM-Z1 / Kimi K2-thinking / Hunyuan-T1 / Doubao-thinking / OpenAI o-series). Normalized by beatra. Clients should NOT echo back next turn.
        tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolCall'
            type: array
          - type: 'null'
          title: Tool Calls
        audio:
          anyOf:
          - $ref: '#/components/schemas/AssistantAudio'
          - type: 'null'
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      type: object
      required:
      - role
      title: AssistantMessage
    NamedFunctionChoice:
      properties:
        type:
          type: string
          const: function
          title: Type
        function:
          additionalProperties:
            type: string
          type: object
          title: Function
          description: '{name: str}'
      type: object
      required:
      - type
      - function
      title: NamedFunctionChoice
    CompletionTokensDetails:
      properties:
        reasoning_tokens:
          type: integer
          title: Reasoning Tokens
          default: 0
        audio_tokens:
          type: integer
          title: Audio Tokens
          default: 0
        accepted_prediction_tokens:
          type: integer
          title: Accepted Prediction Tokens
          default: 0
        rejected_prediction_tokens:
          type: integer
          title: Rejected Prediction Tokens
          default: 0
      type: object
      title: CompletionTokensDetails
    JsonSchemaDef:
      properties:
        name:
          type: string
          title: Name
          description: 'Required by OpenAI: identifier for the schema'
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        schema:
          additionalProperties: true
          type: object
          title: Schema
          description: JSON Schema
        strict:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Strict
      type: object
      required:
      - name
      - schema
      title: JsonSchemaDef
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorResponse
    TextContentPart:
      properties:
        type:
          type: string
          const: text
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
      - type
      - text
      title: TextContentPart
    ToolCallFunction:
      properties:
        name:
          type: string
          title: Name
        arguments:
          type: string
          title: Arguments
          description: JSON-stringified arguments
      type: object
      required:
      - name
      - arguments
      title: ToolCallFunction
    FileData:
      properties:
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
        file_data:
          anyOf:
          - type: string
          - type: 'null'
          title: File Data
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
      type: object
      title: FileData
    FunctionDefinition:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
          description: JSON Schema
        strict:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Strict
      type: object
      required:
      - name
      title: FunctionDefinition