Generate a response

Use the Responses resource when you want the MKA1 API to return text. Start with a plain string for simple prompts. Use message items when you need explicit roles or conversation state. Later sections cover sampling and length limits and reasoning effort. Pausing a background response has its own section in background responses.

Send a simple prompt

Pass a string in input for a single-turn request. The response includes generated text in output_text. If a guardrail blocks the request, output_text is absent and the output carries a refusal instead; see Guardrails.

mka1 llm responses create \
  --model auto \
  --input '"Write a one-sentence summary of the MKA1 API."' \
  -H 'X-On-Behalf-Of: <end-user-id>'

import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const result = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>', // optional — attribute the request to one of your end users
  responsesCreateRequest: {
    model: 'auto',
    input: 'Write a one-sentence summary of the MKA1 API.',
  },
});

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const response = await openai.responses.create({
  model: 'auto',
  input: 'Write a one-sentence summary of the MKA1 API.',
  stream: false,
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Input = ResponsesCreateRequestInput.CreateStr(
        "Write a one-sentence summary of the MKA1 API."),
});

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

res = sdk.llm.responses.create(
    model="auto",
    input="Write a one-sentence summary of the MKA1 API.",
    x_on_behalf_of="<end-user-id>",  # optional — attribute the request to one of your end users
)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "input": "Write a one-sentence summary of the MKA1 API."
  }'

If you are not acting for an end user, omit X-On-Behalf-Of.

Add instructions

Use instructions to define behavior before the model sees the user input. Keep instructions short and specific.

mka1 llm responses create \
  --model auto \
  --instructions 'You are a support assistant. Reply in plain English. Keep answers under 80 words.' \
  --input '"Explain what embeddings are used for."'

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    instructions: 'You are a support assistant. Reply in plain English. Keep answers under 80 words.',
    input: 'Explain what embeddings are used for.',
  },
});

const response = await openai.responses.create({
  model: 'auto',
  instructions: 'You are a support assistant. Reply in plain English. Keep answers under 80 words.',
  input: 'Explain what embeddings are used for.',
  stream: false,
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Instructions = "You are a support assistant. Reply in plain English. Keep answers under 80 words.",
    Input = ResponsesCreateRequestInput.CreateStr("Explain what embeddings are used for."),
});

res = sdk.llm.responses.create(
    model="auto",
    instructions="You are a support assistant. Reply in plain English. Keep answers under 80 words.",
    input="Explain what embeddings are used for.",
)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "instructions": "You are a support assistant. Reply in plain English. Keep answers under 80 words.",
    "input": "Explain what embeddings are used for."
  }'

Send structured messages

Use an array of message items in input when you want explicit roles. Each message item uses type, role, and content.

mka1 llm responses create --body '{
  "model": "auto",
  "input": [
    { "type": "message", "role": "developer", "content": "Answer as a technical writer. Keep the reply concise." },
    { "type": "message", "role": "user", "content": "Draft a short product update about faster response times." }
  ]
}'

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    input: [
      { type: 'message', role: 'developer', content: 'Answer as a technical writer. Keep the reply concise.' },
      { type: 'message', role: 'user', content: 'Draft a short product update about faster response times.' },
    ],
  },
});

const response = await openai.responses.create({
  model: 'auto',
  input: [
    { type: 'message', role: 'developer', content: 'Answer as a technical writer. Keep the reply concise.' },
    { type: 'message', role: 'user', content: 'Draft a short product update about faster response times.' },
  ],
  stream: false,
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Input = ResponsesCreateRequestInput.CreateArrayOfItem(new List<Item>
    {
        Item.CreateInputMessage(new InputMessage()
        {
            Role = InputMessageRole.Developer,
            Content = InputMessageContent1.CreateStr(
                "Answer as a technical writer. Keep the reply concise."),
        }),
        Item.CreateInputMessage(new InputMessage()
        {
            Role = InputMessageRole.User,
            Content = InputMessageContent1.CreateStr(
                "Draft a short product update about faster response times."),
        }),
    }),
});

res = sdk.llm.responses.create(
    model="auto",
    input=[
        {"type": "message", "role": "developer", "content": "Answer as a technical writer. Keep the reply concise."},
        {"type": "message", "role": "user", "content": "Draft a short product update about faster response times."},
    ],
)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "input": [
      { "type": "message", "role": "developer", "content": "Answer as a technical writer. Keep the reply concise." },
      { "type": "message", "role": "user", "content": "Draft a short product update about faster response times." }
    ]
  }'

This pattern is useful when you want the request body to carry the message history directly.

Continue a multi-turn exchange

Use previous_response_id to continue from an earlier response without resending the full history.

mka1 llm responses create \
  --model auto \
  --previous-response-id resp_123 \
  --input '"Now turn that into an email subject line."'

const second = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    previousResponseId: 'resp_123',
    input: 'Now turn that into an email subject line.',
  },
});

const second = await openai.responses.create({
  model: 'auto',
  previous_response_id: 'resp_123',
  input: 'Now turn that into an email subject line.',
  stream: false,
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

// First request
var first = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Input = ResponsesCreateRequestInput.CreateStr("Write a one-line product tagline."),
});

// Second request: continue from the first response
var second = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    PreviousResponseId = first.Id,
    Input = ResponsesCreateRequestInput.CreateStr("Now turn that into an email subject line."),
});

res = sdk.llm.responses.create(
    model="auto",
    previous_response_id="resp_123",
    input="Now turn that into an email subject line.",
)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "previous_response_id": "resp_123",
    "input": "Now turn that into an email subject line."
  }'

If you need a reusable conversation container, create one with the Conversations resource and then pass the conversation ID in conversation.

# Create a conversation
mka1 llm conversations create --body '{
  "metadata": { "session_id": "web-42" }
}'

# Use the conversation in a response request
mka1 llm responses create \
  --model auto \
  --conversation conv_123 \
  --input '"What should I ask next to refine this draft?"'

const conv = await mka1.llm.conversations.create({
  createConversationRequest: {
    metadata: { session_id: 'web-42' },
  },
});

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    conversation: conv.id,
    input: 'What should I ask next to refine this draft?',
  },
});

const conv = await openai.conversations.create({
  metadata: { session_id: 'web-42' },
});

const response = await openai.responses.create({
  model: 'auto',
  conversation: conv.id,
  input: 'What should I ask next to refine this draft?',
  stream: false,
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var conv = await sdk.Llm.Conversations.CreateAsync(body: new CreateConversationRequest()
{
    Metadata = new Dictionary<string, string> { { "session_id", "web-42" } },
});

conv = sdk.llm.conversations.create(
    metadata={"session_id": "web-42"},
)

res = sdk.llm.responses.create(
    model="auto",
    conversation=conv.id,
    input="What should I ask next to refine this draft?",
)

# Create conversation
curl https://apigw.mka1.com/api/v1/llm/conversations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "metadata": { "session_id": "web-42" }
  }'

# Use conversation in a response request
curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "conversation": "conv_123",
    "input": "What should I ask next to refine this draft?"
  }'

See the Conversations and Responses pages in the API Reference for the full resource workflow.

Stream text as it is generated

Set stream to true to receive server-sent events instead of waiting for the full response.

mka1 llm responses create \
  --model auto \
  --input '"Write three release notes bullets for our docs update."' \
  --stream

import { CreateAcceptEnum } from '@meetkai/mka1/sdk/responses';

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    input: 'Write three release notes bullets for our docs update.',
    stream: true,
  },
}, { acceptHeaderOverride: CreateAcceptEnum.textEventStream });

const stream = await openai.responses.create({
  model: 'auto',
  input: 'Write three release notes bullets for our docs update.',
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Input = ResponsesCreateRequestInput.CreateStr(
        "Write three release notes bullets for our docs update."),
    Stream = true,
});

stream = sdk.llm.responses.create(
    model="auto",
    input="Write three release notes bullets for our docs update.",
    stream=True,
)

for event in stream:
    if event.data.type == "response.output_text.delta":
        print(event.data.delta, end="", flush=True)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "input": "Write three release notes bullets for our docs update.",
    "stream": true
  }'

Use streaming when you want to render partial output as it arrives.

Tune sampling and length

Sampling fields change how the model picks each token. Length fields cap how much it writes. All of them are optional and sit at the top level of the request, next to model and input.

mka1 llm responses create --body '{
  "model": "auto",
  "input": "Write a one-sentence summary of the MKA1 API.",
  "temperature": 0.2,
  "max_output_tokens": 400
}'

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    input: 'Write a one-sentence summary of the MKA1 API.',
    temperature: 0.2,
    maxOutputTokens: 400,
  },
});

const response = await openai.responses.create({
  model: 'auto',
  input: 'Write a one-sentence summary of the MKA1 API.',
  temperature: 0.2,
  max_output_tokens: 400,
  stream: false,
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Input = ResponsesCreateRequestInput.CreateStr(
        "Write a one-sentence summary of the MKA1 API."),
    Temperature = 0.2,
    MaxOutputTokens = 400,
});

res = sdk.llm.responses.create(
    model="auto",
    input="Write a one-sentence summary of the MKA1 API.",
    temperature=0.2,
    max_output_tokens=400,
)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "input": "Write a one-sentence summary of the MKA1 API.",
    "temperature": 0.2,
    "max_output_tokens": 400
  }'

The gateway validates every value before it calls the model. A value outside its range returns 400. In the example, check status: if the model hit the 400-token cap, the response is incomplete rather than completed, and usage.output_tokens stays at or below the cap. Some fields below are gateway extensions. They are not part of the OpenAI Responses API, and whether they reach the model depends on its upstream, the provider API the gateway forwards your request to, which speaks either the Responses format or the Completions format.

Field	Accepts	Effect
`temperature`	number, 0 to 2	How random each token pick is. Lower values give steadier output.
`top_p`	number, 0 to 1	Nucleus sampling. The model only considers the tokens that make up the top `top_p` share of probability. Use this or `temperature`, not both.
`max_output_tokens`	integer, 1 or more	Cap on generated tokens. A response cut off at the cap finishes with `status: "incomplete"`.
`stop`	string, or a non-empty array of strings	Stop sequences. Gateway extension. Forwarded to Completions-format models and to providers other than OpenAI; dropped on a Responses-format upstream at `api.openai.com`.
`presence_penalty`	number, -2 to 2	Penalizes tokens that have already appeared, so the model moves on to new topics.
`frequency_penalty`	number, -2 to 2	Penalizes tokens by how often they have appeared, so the model repeats itself less.
`top_k`	integer, 0 or more	Provider-specific top-k sampling. Gateway extension.
`min_p`	number, 0 to 1	Provider-specific min-p sampling. Gateway extension.
`repetition_penalty`	number, 0 or more	Provider-specific repetition penalty. Gateway extension.
`do_sample`	boolean	Provider-specific sampling toggle. Gateway extension.
`truncation`	`"auto"` or `"disabled"`, default `"auto"`	What happens when the input outgrows the context window. `auto` drops the oldest messages; with `disabled` the response fails with status `failed`.

top_logprobs is accepted for OpenAI compatibility but the gateway does not forward it to models yet. Fields marked as gateway extensions are not part of the OpenAI Responses API, so the OpenAI SDK’s types do not know them. Send them with the MKA1 SDK, the CLI, or raw HTTP. Four more gateway extensions pass provider options through untouched: chat_template_kwargs (for example {"enable_thinking": false}), prefill_think (a boolean or prefill text), use_cache, and extra_body, an object merged into the upstream request after the gateway strips any auth, base-URL, and header keys from it. These four, and the provider-specific rows in the table, reach only providers other than OpenAI; on an upstream at api.openai.com the gateway drops them.

Check what a model supports

Not every model accepts every sampling field. GET /api/v1/llm/models/{model_id} returns a capabilities object with two booleans: supports_temperature and supports_top_p. Models that are not LLMs (embeddings, images, speech) report false for both.

mka1 llm models get --model-id meetkai:functionary

const model = await mka1.llm.models.get({ modelId: 'meetkai:functionary' });

console.log(model.capabilities.supportsTemperature, model.capabilities.supportsTopP);

const model = await openai.models.retrieve('meetkai:functionary');

// capabilities is a gateway extension, so the OpenAI SDK's Model type does not declare it
const { capabilities } = model as unknown as {
  capabilities: { supports_temperature: boolean; supports_top_p: boolean };
};
console.log(capabilities.supports_temperature, capabilities.supports_top_p);

using MeetKai.MKA1;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var model = await sdk.Llm.Models.GetAsync(modelId: "meetkai:functionary");

Console.WriteLine($"{model.Object!.Capabilities.SupportsTemperature} {model.Object!.Capabilities.SupportsTopP}");

model = sdk.llm.models.get(model_id="meetkai:functionary")

print(model.capabilities.supports_temperature, model.capabilities.supports_top_p)

curl https://apigw.mka1.com/api/v1/llm/models/meetkai:functionary \
  --header 'Authorization: Bearer <mka1-api-key>'

If you send temperature or top_p to a model that reports false, the gateway does not reject the request. It drops that one field before calling the model, forwards everything else, and the response succeeds with the model’s own default sampling. Nothing in the response says the field was dropped, so check the model’s capabilities first when the setting matters.

Control reasoning

Reasoning models think before they answer. The reasoning object sets how much thinking you want and whether you see it:

effort: none, minimal, low, medium, high, or xhigh.
summary: auto, concise, or detailed. Asks the model to return a readable summary of its reasoning.

Both keys must be present whenever you send the object. Set the one you are not using to null. {"effort": "low"} on its own fails validation. Whether summary reaches the model depends on the upstream. A Responses-format upstream gets both keys. A Completions-format upstream gets effort (as reasoning_effort) and the gateway drops summary.

mka1 llm responses create --body '{
  "model": "auto",
  "input": "Which of 17, 21, and 23 are prime? Answer in one line.",
  "reasoning": { "effort": "low", "summary": null }
}'

import type { ResponseObject } from '@meetkai/mka1/models/components';

const result = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'auto',
    input: 'Which of 17, 21, and 23 are prime? Answer in one line.',
    reasoning: { effort: 'low', summary: null },
  },
}) as ResponseObject;

console.log(result.usage.outputTokensDetails.reasoningTokens);

const response = await openai.responses.create({
  model: 'auto',
  input: 'Which of 17, 21, and 23 are prime? Answer in one line.',
  reasoning: { effort: 'low', summary: null },
  stream: false,
});

console.log(response.usage?.output_tokens_details.reasoning_tokens);

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "auto",
    Input = ResponsesCreateRequestInput.CreateStr(
        "Which of 17, 21, and 23 are prime? Answer in one line."),
    Reasoning = new ReasoningConfiguration()
    {
        Effort = ReasoningConfigurationEffort.Low,
        Summary = null,
    },
});

Console.WriteLine(res.ResponseObject!.Usage.OutputTokensDetails.ReasoningTokens);

res = sdk.llm.responses.create(
    model="auto",
    input="Which of 17, 21, and 23 are prime? Answer in one line.",
    reasoning={"effort": "low", "summary": None},
)

print(res.usage.output_tokens_details.reasoning_tokens)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "auto",
    "input": "Which of 17, 21, and 23 are prime? Answer in one line.",
    "reasoning": { "effort": "low", "summary": null }
  }'

The OpenAI SDK’s ReasoningEffort type does not include none or xhigh; send those with the MKA1 SDK, the CLI, or raw HTTP. Reasoning shows up in three places:

output can contain an item with type: "reasoning". Its summary array holds summary_text parts, and content (when present) holds the raw reasoning_text parts. Add "reasoning.encrypted_content" to include to get encrypted_content as well.
usage.output_tokens_details.reasoning_tokens is the share of output_tokens the model spent thinking. Reasoning tokens are output tokens, so they count against max_output_tokens.
In a stream, response.reasoning_text.delta and response.reasoning_summary_text.delta events typically arrive before the response.output_text.delta events. The streaming output latency benchmark shows this order on a live model.

For a model that does not reason, the gateway strips the reasoning object before the call, the same way it drops temperature and top_p for models that do not support them. The request still succeeds. The capabilities object above has no reasoning flag, so there is no way to check this ahead of time; usage.output_tokens_details.reasoning_tokens shows afterwards how much reasoning happened. When you send model: "auto", the gateway applies the organization’s auto policy for Responses. The default is a direct model-registry alias. An organization admin can configure a balanced policy that asks an LLM judge to choose among eligible models using capability, price, gateway latency, comparable evals, request requirements, and conversation continuity. Routing does not change the reasoning.effort you send. Auto routing explains the policy and its failure and privacy behavior.

Pause a background response

A background response can call the sleep tool to wait up to 20 minutes for a webhook or an outside job, and you can wake it early with follow-up input. See background responses.

Next steps

Review the API overview for authentication and base URL details
See background responses when you need to offload long-running work and poll or stream for results
See manage conversations to organize multi-turn exchanges into reusable conversation containers
See manage agents when you want reusable agent definitions and persisted runs
See streaming output latency for measured time to first streamed token on the Responses API

Getting started

Responses

Features

Compute

CLI

Recipes

Benchmarks

Infrastructure

Generate a response

Send a simple prompt

Add instructions

Send structured messages

Continue a multi-turn exchange

Stream text as it is generated

Tune sampling and length

Check what a model supports

Control reasoning

Pause a background response

Next steps

​Send a simple prompt

​Add instructions

​Send structured messages

​Continue a multi-turn exchange

​Stream text as it is generated

​Tune sampling and length

​Check what a model supports

​Control reasoning

​Pause a background response

​Next steps

Send a simple prompt

Add instructions

Send structured messages

Continue a multi-turn exchange

Stream text as it is generated

Tune sampling and length

Check what a model supports

Control reasoning

Pause a background response

Next steps