{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beatra-ai/json-schema/beatra-ai-chat-completion-request-schema.json",
  "title": "ChatCompletionRequest",
  "description": "Request body for POST /v1/chat/completions.\n\nOpenAI-compatible request with an explicit, typed field surface. Raw\nupstream passthrough is intentionally forbidden because it can override\nthe routed model, messages, streaming mode, or operator service tier.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beatra-ai-api-openapi.json#/components/schemas/ChatCompletionRequest",
  "properties": {
    "model": {
      "type": "string",
      "title": "Model",
      "description": "Model name (e.g. 'gpt-4o-mini', 'qwen-max', 'auto')"
    },
    "messages": {
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/SystemMessage"
          },
          {
            "$ref": "#/$defs/UserMessage"
          },
          {
            "$ref": "#/$defs/AssistantMessage"
          },
          {
            "$ref": "#/$defs/ToolMessage"
          }
        ]
      },
      "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": "#/$defs/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": "#/$defs/Tool"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tools"
    },
    "tool_choice": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/$defs/NamedFunctionChoice"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tool Choice"
    },
    "parallel_tool_calls": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Parallel Tool Calls"
    },
    "response_format": {
      "anyOf": [
        {
          "oneOf": [
            {
              "$ref": "#/$defs/ResponseFormatText"
            },
            {
              "$ref": "#/$defs/ResponseFormatJsonObject"
            },
            {
              "$ref": "#/$defs/ResponseFormatJsonSchema"
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Response Format"
    },
    "reasoning": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "$ref": "#/$defs/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": "#/$defs/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"
  ],
  "$defs": {
    "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"
    },
    "AssistantMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "assistant",
          "title": "Role"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "$ref": "#/$defs/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": "#/$defs/ToolCall"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Tool Calls"
        },
        "audio": {
          "anyOf": [
            {
              "$ref": "#/$defs/AssistantAudio"
            },
            {
              "type": "null"
            }
          ]
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        }
      },
      "type": "object",
      "required": [
        "role"
      ],
      "title": "AssistantMessage"
    },
    "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"
    },
    "FileContentPart": {
      "properties": {
        "type": {
          "type": "string",
          "const": "file",
          "title": "Type"
        },
        "file": {
          "$ref": "#/$defs/FileData"
        }
      },
      "type": "object",
      "required": [
        "type",
        "file"
      ],
      "title": "FileContentPart"
    },
    "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"
    },
    "ImageUrlContentPart": {
      "properties": {
        "type": {
          "type": "string",
          "const": "image_url",
          "title": "Type"
        },
        "image_url": {
          "$ref": "#/$defs/ImageUrlData"
        }
      },
      "type": "object",
      "required": [
        "type",
        "image_url"
      ],
      "title": "ImageUrlContentPart"
    },
    "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": "#/$defs/InputAudioData"
        }
      },
      "type": "object",
      "required": [
        "type",
        "input_audio"
      ],
      "title": "InputAudioContentPart"
    },
    "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"
    },
    "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"
    },
    "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"
    },
    "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.\n\nThe object form of the `reasoning` field. The bare booleans are sugar:\n`reasoning: true` == `{}` (on at the model default), `reasoning: false`\n== reasoning off. Engine-specific wire differences (DeepSeek `enabled`,\nMiniMax `adaptive`, NVIDIA `chat_template_kwargs`) are translated\nserver-side."
    },
    "ResponseFormatJsonObject": {
      "properties": {
        "type": {
          "type": "string",
          "const": "json_object",
          "title": "Type",
          "default": "json_object"
        }
      },
      "type": "object",
      "title": "ResponseFormatJsonObject"
    },
    "ResponseFormatJsonSchema": {
      "properties": {
        "type": {
          "type": "string",
          "const": "json_schema",
          "title": "Type",
          "default": "json_schema"
        },
        "json_schema": {
          "$ref": "#/$defs/JsonSchemaDef"
        }
      },
      "type": "object",
      "required": [
        "json_schema"
      ],
      "title": "ResponseFormatJsonSchema"
    },
    "ResponseFormatText": {
      "properties": {
        "type": {
          "type": "string",
          "const": "text",
          "title": "Type",
          "default": "text"
        }
      },
      "type": "object",
      "title": "ResponseFormatText"
    },
    "StreamOptions": {
      "properties": {
        "include_usage": {
          "type": "boolean",
          "title": "Include Usage",
          "default": false
        }
      },
      "type": "object",
      "title": "StreamOptions"
    },
    "SystemMessage": {
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "system",
            "developer"
          ],
          "title": "Role"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "$ref": "#/$defs/TextContentPart"
              },
              "type": "array"
            }
          ],
          "title": "Content"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        }
      },
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "title": "SystemMessage"
    },
    "TextContentPart": {
      "properties": {
        "type": {
          "type": "string",
          "const": "text",
          "title": "Type"
        },
        "text": {
          "type": "string",
          "title": "Text"
        }
      },
      "type": "object",
      "required": [
        "type",
        "text"
      ],
      "title": "TextContentPart"
    },
    "Tool": {
      "properties": {
        "type": {
          "type": "string",
          "const": "function",
          "title": "Type",
          "default": "function"
        },
        "function": {
          "$ref": "#/$defs/FunctionDefinition"
        }
      },
      "type": "object",
      "required": [
        "function"
      ],
      "title": "Tool"
    },
    "ToolCall": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id"
        },
        "type": {
          "type": "string",
          "const": "function",
          "title": "Type",
          "default": "function"
        },
        "function": {
          "$ref": "#/$defs/ToolCallFunction"
        }
      },
      "type": "object",
      "required": [
        "id",
        "function"
      ],
      "title": "ToolCall"
    },
    "ToolCallFunction": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "arguments": {
          "type": "string",
          "title": "Arguments",
          "description": "JSON-stringified arguments"
        }
      },
      "type": "object",
      "required": [
        "name",
        "arguments"
      ],
      "title": "ToolCallFunction"
    },
    "ToolMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "tool",
          "title": "Role"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "$ref": "#/$defs/TextContentPart"
              },
              "type": "array"
            }
          ],
          "title": "Content"
        },
        "tool_call_id": {
          "type": "string",
          "title": "Tool Call Id"
        }
      },
      "type": "object",
      "required": [
        "role",
        "content",
        "tool_call_id"
      ],
      "title": "ToolMessage"
    },
    "UserMessage": {
      "properties": {
        "role": {
          "type": "string",
          "const": "user",
          "title": "Role"
        },
        "content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "items": {
                "oneOf": [
                  {
                    "$ref": "#/$defs/TextContentPart"
                  },
                  {
                    "$ref": "#/$defs/ImageUrlContentPart"
                  },
                  {
                    "$ref": "#/$defs/VideoUrlContentPart"
                  },
                  {
                    "$ref": "#/$defs/InputAudioContentPart"
                  },
                  {
                    "$ref": "#/$defs/FileContentPart"
                  }
                ]
              },
              "type": "array"
            }
          ],
          "title": "Content"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        }
      },
      "type": "object",
      "required": [
        "role",
        "content"
      ],
      "title": "UserMessage"
    },
    "VideoUrlContentPart": {
      "properties": {
        "type": {
          "type": "string",
          "const": "video_url",
          "title": "Type"
        },
        "video_url": {
          "$ref": "#/$defs/VideoUrlData"
        }
      },
      "type": "object",
      "required": [
        "type",
        "video_url"
      ],
      "title": "VideoUrlContentPart"
    },
    "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"
    }
  }
}