--- title: "Create chat completion (OpenAI-compatible)" method: POST path: "/v1/chat/completions" tags: ["chat"] --- # Create chat completion (OpenAI-compatible) `POST /v1/chat/completions` ## Request - Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.beatra.ai/v1/chat/completions` - Auth: none declared 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`. ## Headers - `x-request-id` string, nullable - `authorization` string, nullable ## Request body - ChatCompletionRequest: 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. - `model` string, required: Model name (e.g. 'gpt-4o-mini', 'qwen-max', 'auto') - `messages` union[], required - union - SystemMessage - `role` 'system' | 'developer', required - `content` union, required - string - TextContentPart[] - `type` 'text', required - `text` string, required - `name` string, nullable - UserMessage - `role` 'user', required - `content` union, required - string - union[] - union - … - `name` string, nullable - AssistantMessage - `role` 'assistant', required - `content` union - string - TextContentPart[] - `type` 'text', required - `text` string, required - `refusal` string, nullable - `reasoning_content` string, nullable: 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` ToolCall[], nullable - `id` string, required - `type` 'function' - `function` ToolCallFunction, required - `name` string, required - `arguments` string, required: JSON-stringified arguments - `audio` AssistantAudio - `id` string, nullable - `data` string, nullable - `expires_at` integer, nullable - `transcript` string, nullable - `name` string, nullable - ToolMessage - `role` 'tool', required - `content` union, required - string - TextContentPart[] - `type` 'text', required - `text` string, required - `tool_call_id` string, required - `temperature` number, nullable - `top_p` number, nullable - `max_tokens` integer, nullable: Legacy; reasoning models reject this. beatra maps to max_completion_tokens. - `max_completion_tokens` integer, nullable - `n` integer, nullable - `seed` integer, nullable - `stop` union - string - string[] - `stream` boolean - `stream_options` StreamOptions - `include_usage` boolean - `frequency_penalty` number, nullable - `presence_penalty` number, nullable - `logit_bias` object, nullable - `logprobs` boolean, nullable - `top_logprobs` integer, nullable - `tools` Tool[], nullable - `type` 'function' - `function` FunctionDefinition, required - `name` string, required - `description` string, nullable - `parameters` object: JSON Schema - `strict` boolean, nullable - `tool_choice` union - string - NamedFunctionChoice - `type` 'function', required - `function` object, required: {name: str} - `parallel_tool_calls` boolean, nullable - `response_format` union - ResponseFormatText - `type` 'text' - ResponseFormatJsonObject - `type` 'json_object' - ResponseFormatJsonSchema - `type` 'json_schema' - `json_schema` JsonSchemaDef, required - `name` string, required: Required by OpenAI: identifier for the schema - `description` string, nullable - `schema` object, required: JSON Schema - `strict` boolean, nullable - `reasoning` union - boolean - ReasoningConfig: 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. - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'max', nullable - `mode` 'fixed' | 'adaptive', nullable - `expose_trace` boolean, nullable: Return the reasoning trace separately (maps to MiniMax reasoning_split). - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high' | 'max' | 'xhigh', nullable - `audio` AudioOutputConfig - `voice` string, required - `format` 'wav' | 'mp3' | 'flac' | 'opus' | 'pcm16', required - `modalities` string[], nullable - `metadata` object, nullable - `store` boolean, nullable - `service_tier` string, nullable - `safety_identifier` string, nullable - `prompt_cache_key` string, nullable - `user` string, nullable: Deprecated; use safety_identifier ## Response `200` Sync completion or streaming chat completion chunks - ChatCompletionResponse: Standard OpenAI ChatCompletion response plus usage.credits. - `id` string, required - `object` 'chat.completion' - `created` integer, required - `model` string, required: Resolved model snapshot (OpenAI convention) - `system_fingerprint` string, nullable - `service_tier` string, nullable - `choices` ChatChoice[], required - `index` integer, required - `message` AssistantMessage, required - `role` 'assistant', required - `content` union - string - TextContentPart[] - `type` 'text', required - `text` string, required - `refusal` string, nullable - `reasoning_content` string, nullable: 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` ToolCall[], nullable - `id` string, required - `type` 'function' - `function` ToolCallFunction, required - `name` string, required - `arguments` string, required: JSON-stringified arguments - `audio` AssistantAudio - `id` string, nullable - `data` string, nullable - `expires_at` integer, nullable - `transcript` string, nullable - `name` string, nullable - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call', nullable, required - `logprobs` Logprobs - `content` LogprobToken[], nullable - `token` string, required - `logprob` number, required - `bytes` integer[], nullable - `top_logprobs` object[] - `refusal` LogprobToken[], nullable - `token` string, required - `logprob` number, required - `bytes` integer[], nullable - `top_logprobs` object[] - `usage` ChatUsage, required - `prompt_tokens` integer, required - `completion_tokens` integer, required - `total_tokens` integer, required - `cache_creation_input_tokens` integer, nullable - `cache_read_input_tokens` integer, nullable - `reasoning_tokens` integer, nullable - `prompt_tokens_details` PromptTokensDetails - `cached_tokens` integer - `audio_tokens` integer - `completion_tokens_details` CompletionTokensDetails - `reasoning_tokens` integer - `audio_tokens` integer - `accepted_prediction_tokens` integer - `rejected_prediction_tokens` integer - `credits` string, nullable: Credits charged for this call. Populated by PR-2. ## Other responses - `402`: Account balance too low - `422`: Unprocessable Entity - `502`: Model request failed - `503`: Model temporarily unavailable --- [API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)