Chat completions

POST https://api.llmbase.ai/v1/chat/completions

The chat completions endpoint follows the OpenAI Chat API. OpenAI SDK chat clients can use it by changing the base URL, API key, and model ID.

This page documents the direct inference API. If you are configuring OpenClaw, Hermes, or another external agent to use a Pro chat subscription, use https://llmbase.ai/api/v1/agents/chat/completions with a llmbase_chat_... key instead. See Agent integrations.

Request body

Required fields

Field	Type	Description
model	string	Model ID returned by GET /v1/models. See Models.
messages	array	Conversation history. At least one message required.

Messages

Each message is an object with a role and content. Assistant messages can also include tool_calls, and tool results use role: "tool" with the matching tool_call_id.

[
  { "role": "system",    "content": "You are a helpful assistant." },
  { "role": "user",      "content": "Summarise this article: ..." },
  { "role": "assistant", "content": "Here is a summary: ..." },
  { "role": "user",      "content": "Make it shorter." }
]

Roles:

Role	Description
system	Sets the behaviour and persona of the assistant
user	A message from the end user
assistant	A previous response from the model for multi-turn conversations
tool	Result returned by your application after executing a model-requested tool

User messages support multimodal content as an array of parts:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
  ]
}

Optional parameters

Parameter	Type	Default	Description
stream	boolean	false	Stream tokens as SSE. See Streaming.
temperature	number	model default	Sampling temperature 0-2. Lower = more deterministic.
top_p	number	model default	Nucleus sampling probability mass 0-1.
top_k	number	model default	Limit sampling to the top K tokens when supported by the selected model.
min_p	number	model default	Minimum probability sampling cutoff when supported.
max_tokens	integer	model max	Maximum tokens to generate.
frequency_penalty	number	0	Penalises repeated tokens by frequency -2.0-2.0.
presence_penalty	number	0	Penalises tokens that have appeared at all -2.0-2.0.
repetition_penalty	number	model default	Supported repetition penalty.
stop	string | string[]	-	Up to 4 sequences where generation stops.
seed	integer	-	Fixed seed for deterministic outputs, best-effort.
logprobs	boolean	-	Return output-token log probabilities on models that expose them.
top_logprobs	integer	-	Return the most likely token alternatives for each generated token. Requires logprob support.
response_format	object	-	Request JSON output. See Structured outputs.
reasoning_effort	string	-	Portable reasoning-effort hint on models that advertise reasoning. Check supported_reasoning_efforts in model metadata when present; DeepSeek V4 uses high and max.
prompt_cache_key	string	-	LLMBase prompt-cache namespace. See Prompt caching.
tools	array	-	OpenAI-compatible function tool definitions. See Tools.
tool_choice	string | object	auto	auto, none, required, or a specific function tool.

LLMBase documents the portable OpenAI-compatible fields it supports directly. Non-standard fields such as provider, route, models, plugins, debug, service_tier, and top-level cache_control are not part of the LLMBase direct inference contract. Choose an LLMBase model ID and use prompt_cache_key for prompt-cache grouping.

Choosing request options

Start with the smallest request surface that solves the job:

Goal	Recommended fields
Chat UI	messages, stream: true, max_tokens
Backend extraction	response_format, low temperature, max_tokens
Tool-using agent	tools, tool_choice, prompt_cache_key
Confidence scoring	logprobs, top_logprobs on a model that supports logprobs
Cost control	max_tokens, prompt_cache_key, model pricing from /v1/models?metadata=true

If a request needs a model-specific capability, choose the model from /v1/models?metadata=true first. LLMBase rejects unsupported combinations instead of silently ignoring required features.

Non-streaming response

{
  "id": "chatcmpl-a1b2c3d4e5f6a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1741000000,
  "model": "<model-id-from-/v1/models>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I can help you with a wide range of tasks..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 48,
    "total_tokens": 60,
    "prompt_tokens_details": {
      "cached_tokens": 8
    }
  }
}

finish_reason values

Value	Meaning
stop	Model finished naturally
length	max_tokens limit reached
content_filter	Response was filtered
tool_calls	Model called one or more tools

Full example

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.llmbase.ai/v1",
  apiKey: process.env.LLMBASE_API_KEY,
});

const response = await client.chat.completions.create({
  model: "<model-id-from-/v1/models>",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Explain recursion in one sentence." },
  ],
  temperature: 0.7,
  max_tokens: 100,
});

console.log(response.choices[0].message.content);

Error responses

Errors are returned as JSON with an error object:

{
  "error": {
    "message": "Model not found: unknown/model",
    "type": "invalid_request_error"
  }
}

HTTP status	Meaning
400	Bad request: missing or invalid fields
401	Authentication failed: check your API key
404	Model not found
502	Selected model temporarily unavailable: retry with backoff

Advanced guides

• Streaming for Server-Sent Events and SDK streams
• Tools for function calling loops
• Structured outputs for JSON mode and JSON Schema
• Prompt caching for repeated long prompts and cache-read billing
• Model availability for temporary errors and retry guidance
• Reasoning for reasoning_effort and thinking traces