Chat Completions Guide¶

Chat completions are the primary way to interact with models on OpenRouter. This library provides multiple ways to create and handle these requests.

Non-Streaming Requests¶

To get a complete response at once, use the client.chat { } DSL.

val response = client.chat {
    model = "openai/gpt-4o-mini"
    userMessage("What is the capital of France?")
    temperature = 0.7
}

println(response.choices.first().message?.content)

Request Parameters¶

You can configure several parameters in the request:

model: The model ID (e.g., openai/gpt-4o-mini, anthropic/claude-3-haiku).
messages: A list of messages (use builder methods below).
temperature: Controls randomness (0.0 to 2.0).
maxTokens: The maximum number of tokens to generate.
topP: Nucleus sampling parameter.
topK: Top-K sampling parameter.
seed: Random seed for deterministic output.

Message Types¶

OpenRouter supports several message types, which you can add easily using the DSL.

System Message¶

Used to set the behavior and persona of the assistant.

systemMessage("You are a concise technical writer.")

User Message¶

The input from the user.

userMessage("Explain quantum entanglement.")

Assistant Message¶

A message previously generated by the model.

assistantMessage("Quantum entanglement is a physical phenomenon...")

Tool Message¶

The result of a tool call.

toolMessage(toolCallId = "id_123", content = "The weather is 22°C")

Response Structure¶

The ChatCompletionResponse object contains the following:

id: Unique identifier for the completion.
choices: A list of generated choices (usually one).
- message: The generated message.
- finishReason: Why the generation stopped (e.g., stop, length).
usage: Token usage information for the request.
- promptTokens: Tokens used in the prompt.
- completionTokens: Tokens generated.
- totalTokens: Sum of prompt and completion tokens.

Using l1 Types Directly¶

If you need more control or want to reuse request objects, you can use the low-level l1 data models.

import dev.toliner.openrouter.l1.chat.*

val request = ChatCompletionRequest(
    model = "openai/gpt-4o-mini",
    messages = listOf(
        ChatMessage.System(content = MessageContent.Text("Be helpful.")),
        ChatMessage.User(content = MessageContent.Text("Hi!"))
    )
)

val response = client.chat.complete(request)