OpenAIChatCompletionRequest

@Serializable
data class OpenAIChatCompletionRequest(val model: String, val messages: List<OpenAIMessageParam>, val audio: OpenAIChatCompletionAudioParam? = null, val frequencyPenalty: Double? = null, val logitBias: Map<String, Int>? = null, val logprobs: Boolean? = null, val maxCompletionTokens: Int? = null, val maxTokens: Int? = null, val metadata: OpenAIMetadata? = null, val modalities: List<OpenAIModality>? = listOfNotNull(OpenAIModality.Text, OpenAIModality.Audio.takeIf { audio != null }), val n: Int? = null, val parallelToolCalls: Boolean? = null, val presencePenalty: Double? = null, val responseFormat: OpenAIResponseFormat? = null, val seed: Long? = null, val serviceTier: OpenAIServiceTier? = null, val stop: OpenAIStop? = null, val store: Boolean? = null, val streamOptions: OpenAIStreamOptions? = null, val temperature: Double? = null, val toolChoice: OpenAIToolChoice? = null, val topLogprobs: Int? = null, val topP: Double? = null, val tools: List<OpenAiChatCompletionFunctionTool> = emptyList(), val user: String? = null, val safetyIdentifier: String? = null, val verbosity: OpenAIVerbosity? = null, val reasoningEffort: OpenAIReasoningEffort? = null, stream: Boolean = false)

OpenAI chat completion request body.

Represents the raw JSON payload sent to the /chat/completions endpoint. For provider-agnostic usage, prefer ChatRequest with toOpenAIChatCompletionRequest, or build instances with the io.kory.openai.completions.dsl.openAIChatCompletionRequest DSL.

Samples

// Initial conversation history.
val messages: List<OpenAIMessageParam> = openAIMessageParams {
    system("You are a helpful assistant.")
    user("What's the weather like in London?")
}

// Tool definition with strict schema adherence.
val getWeatherTool = OpenAiChatCompletionFunctionTool(
    type = "function",
    function = OpenAIFunctionDefinition(
        name = "get_weather",
        description = "Gets the current weather for a city",
        parameters = buildJsonObject {
            put("type", "object")
            putJsonObject("properties") {
                putJsonObject("city") { put("type", "string") }
            }
            putJsonArray("required") { add("city") }
        },
        strict = true
    )
)

// Build a fully configured request with the DSL.
return openAIChatCompletionRequest(model = "gpt-5.6-sol") {
    temperature = 0.7
    topP = 1.0
    maxCompletionTokens = 1024
    seed = 42L
    stop = OpenAIStop.OpenAIList(listOf("\n\n", "###"))
    presencePenalty = 0.1
    frequencyPenalty = 0.1
    logprobs = true
    topLogprobs = 5
    parallelToolCalls = true
    toolChoice = OpenAIToolChoice.Auto
    responseFormat = OpenAIResponseFormat.JsonObject
    verbosity = OpenAIVerbosity.LOW
    serviceTier = OpenAIServiceTier.Auto
    store = false
    safetyIdentifier = "user-123"
    metadata = openAIMetadata {
        "project" to "kory"
         "env" to "examples"
    }
    streamOptions = OpenAIStreamOptions(includeUsage = true)

    messages(messages)

    tool(getWeatherTool)
}

Constructors

Link copied to clipboard
constructor(model: String, messages: List<OpenAIMessageParam>, audio: OpenAIChatCompletionAudioParam? = null, frequencyPenalty: Double? = null, logitBias: Map<String, Int>? = null, logprobs: Boolean? = null, maxCompletionTokens: Int? = null, maxTokens: Int? = null, metadata: OpenAIMetadata? = null, modalities: List<OpenAIModality>? = listOfNotNull(OpenAIModality.Text, OpenAIModality.Audio.takeIf { audio != null }), n: Int? = null, parallelToolCalls: Boolean? = null, presencePenalty: Double? = null, responseFormat: OpenAIResponseFormat? = null, seed: Long? = null, serviceTier: OpenAIServiceTier? = null, stop: OpenAIStop? = null, store: Boolean? = null, streamOptions: OpenAIStreamOptions? = null, temperature: Double? = null, toolChoice: OpenAIToolChoice? = null, topLogprobs: Int? = null, topP: Double? = null, tools: List<OpenAiChatCompletionFunctionTool> = emptyList(), user: String? = null, safetyIdentifier: String? = null, verbosity: OpenAIVerbosity? = null, reasoningEffort: OpenAIReasoningEffort? = null, stream: Boolean = false)
constructor(model: String, messages: List<OpenAIMessageParam>, audio: OpenAIChatCompletionAudioParam? = null, frequencyPenalty: Double? = null, logitBias: Map<String, Int>? = null, logprobs: Boolean? = null, maxCompletionTokens: Int? = null, maxTokens: Int? = null, metadata: OpenAIMetadata? = null, modalities: List<OpenAIModality>? = listOfNotNull(OpenAIModality.Text, OpenAIModality.Audio.takeIf { audio != null }), choicesCount: Int? = null, parallelToolCalls: Boolean? = null, presencePenalty: Double? = null, responseFormat: OpenAIResponseFormat? = null, seed: Long? = null, serviceTier: OpenAIServiceTier? = null, stop: OpenAIStop? = null, store: Boolean? = null, streamOptions: OpenAIStreamOptions? = null, temperature: Double? = null, toolChoice: OpenAIToolChoice? = null, topLogprobs: Int? = null, topP: Double? = null, tools: List<OpenAiChatCompletionFunctionTool> = emptyList(), user: String? = null, safetyIdentifier: String? = null, verbosity: OpenAIVerbosity? = null, reasoningEffort: OpenAIReasoningEffort? = null)

Secondary constructor using choicesCount as an alias for n.

Properties

Link copied to clipboard

Audio output parameters for audio generation. null disables audio output.

Link copied to clipboard
@SerialName(value = "frequency_penalty")
val frequencyPenalty: Double?

Penalty for token frequency (-2.0 to 2.0). Positive values decrease repetition.

Link copied to clipboard
@SerialName(value = "logit_bias")
val logitBias: Map<String, Int>?

Modifies the likelihood of specified tokens appearing in the completion. Maps token IDs to a bias value from -100 to 100. null omits the field.

Link copied to clipboard

Whether to return log probabilities of the output tokens. null omits the field.

Link copied to clipboard
@SerialName(value = "max_completion_tokens")
val maxCompletionTokens: Int?

Upper bound for tokens generated in a completion, including visible output tokens and reasoning tokens.

Link copied to clipboard
@SerialName(value = "max_tokens")
val maxTokens: Int?

The maximum number of tokens that can be generated. Deprecated in favor of maxCompletionTokens and not compatible with reasoning models. null omits the field.

Link copied to clipboard

The list of message parameters.

Link copied to clipboard

Set of up to 16 key-value pairs attached to the request object. null omits the field.

Link copied to clipboard

Output modalities to generate (e.g. text, audio).

Link copied to clipboard

The model identifier (e.g. "gpt-5.6-sol").

Link copied to clipboard
val n: Int?

Number of chat completion choices to generate for each input message.

Link copied to clipboard
@SerialName(value = "parallel_tool_calls")
val parallelToolCalls: Boolean?

Whether to enable parallel function calling during tool use. null omits the field (provider default applies).

Link copied to clipboard
@SerialName(value = "presence_penalty")
val presencePenalty: Double?

Penalty for token presence (-2.0 to 2.0). Positive values increase the likelihood of talking about new topics.

Link copied to clipboard
@SerialName(value = "reasoning_effort")
val reasoningEffort: OpenAIReasoningEffort?

Reasoning effort level. null uses provider default.

Link copied to clipboard
@SerialName(value = "response_format")
val responseFormat: OpenAIResponseFormat?

An object specifying the format that the model must output. null uses the default text format.

Link copied to clipboard
@SerialName(value = "safety_identifier")
val safetyIdentifier: String?

A stable identifier for users of your application that may be violating usage policies. Recommend hashing usernames or emails to avoid sending identifying information. Max 64 characters. null omits the field.

Link copied to clipboard
val seed: Long?

Beta. If specified, the system makes a best effort to sample deterministically, such that repeated requests with the same seed and parameters return the same result. Determinism is not guaranteed. null omits the field.

Link copied to clipboard
@SerialName(value = "service_tier")
val serviceTier: OpenAIServiceTier?

Specifies the processing type used for serving the request. null omits the field (defaults to auto).

Link copied to clipboard

Up to 4 sequences where the API stops generating further tokens. Not supported by the latest reasoning models. null omits the field.

Link copied to clipboard

Whether to store the output of this request for use in model distillation or evals products. null omits the field.

Link copied to clipboard
@SerialName(value = "stream_options")
val streamOptions: OpenAIStreamOptions?

Options for streaming responses. Only set this when stream is true.

Link copied to clipboard

Sampling temperature (0.0–2.0). Higher values make output more random.

Link copied to clipboard
@SerialName(value = "tool_choice")
val toolChoice: OpenAIToolChoice?

Controls which (if any) tool is called by the model. null uses the default: none when no tools are present, auto when tools are present.

Link copied to clipboard

Available tool definitions. Defaults to an empty list (no tools).

Link copied to clipboard
@SerialName(value = "top_logprobs")
val topLogprobs: Int?

An integer between 0 and 20 specifying the maximum number of most likely tokens to return at each token position. Requires logprobs set to true.

Link copied to clipboard
@SerialName(value = "top_p")
val topP: Double?

Nucleus sampling parameter (0.0–1.0). Alternative to temperature.

Link copied to clipboard
val user: String?

Deprecated. Replaced by safetyIdentifier and prompt_cache_key. A stable identifier for end-users used to boost cache hit rates and detect abuse.

Link copied to clipboard

Constrains the verbosity of the model's response. null uses the default (medium).

Functions

Link copied to clipboard

Returns a copy of this request with streaming enabled.