API reference

Responses

POST /v1/responses takes a request in the OpenAI Responses format. Every request stands alone: nothing is stored between calls.

POSThttps://gateway.kalsenti.ai/v1/responses
On this page

Request body

curl https://gateway.kalsenti.ai/v1/responses \
  -H "Authorization: Bearer $KALSENTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017-raw",
    "instructions": "Answer in one sentence.",
    "input": "Why is the sea salty?"
  }'

Headers are the same as for chat completions, including the optional Idempotency-Key.

Body

modelstringrequired
A model id from GET /v1/models.
inputstring or arrayrequired
A string, or a list of items making up the conversation. See Input items.
instructionsstring
Guidance placed before the input, like a system message.
max_output_tokensinteger
The most tokens the reply may use, at least 1. Left out, it’s 16,000, and it never goes above the model’s own maximum.
streamboolean
Send the reply as named server-sent events. See Streaming.
temperaturenumber
Passed to the model as given.
top_pnumber
Passed to the model as given.
toolsarray
Functions the model may call, as { "type": "function", "name", "description", "parameters" }. Built-in tool types work on some models only, as for chat completions.
tool_choicestring or object
"auto", "none", "required" or { "type": "function", "name": "…" }.
reasoningobject
{ "effort": "low" }, with minimal, low, medium or high. Models that don’t reason ignore it.
textobject
text.format asks for structured output. Models that can’t do it refuse the request with a 400.

Other fields are ignored. store is always treated as false.

Input items

  • Messages, with a role of system, developer, user or assistant. Their content is a string or a list of input_text, output_text and input_image parts. An image is given by its image_url: a web address or a base64 data: URL.
  • function_call items the model made earlier, and your function_call_output items answering them by call_id.
  • reasoning items from an earlier reply, which are passed back when they carry encrypted_content.

Other item types are skipped. As nothing is stored between requests, send the whole conversation each time:

Continuing after a function call
"input": [
  { "role": "user", "content": "What is the weather in Leeds?" },
  { "type": "function_call", "call_id": "call_4b1e", "name": "get_weather", "arguments": "{\"city\":\"Leeds\"}" },
  { "type": "function_call_output", "call_id": "call_4b1e", "output": "{\"temp_c\": 11, \"sky\": \"overcast\"}" }
]

Response

Response
{
  "id": "resp_3c81f04d9a2b6e7105c4d8af",
  "object": "response",
  "created_at": 1793270400,
  "status": "completed",
  "incomplete_details": null,
  "model": "deepseek-v4.1-flash-1017-raw",
  "output": [
    {
      "id": "msg_a17e09c3d54b28f6e0913b7d",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind." }
      ]
    }
  ],
  "store": false,
  "output_text": "Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind.",
  "usage": {
    "input_tokens": 21,
    "output_tokens": 23,
    "total_tokens": 44
  }
}
outputarray
In order: reasoning items with a summary, message items with output_text content, and function_call items with a call_id, name and arguments.
output_textstring
All the reply’s text in one string.
statusstring
completed, or incomplete when the reply was cut short. The last output item is then incomplete too.
incomplete_detailsobject or null
Why an incomplete reply stopped: { "reason": "max_output_tokens" } when it reached max_output_tokens, or { "reason": "content_filter" } when the model’s host stopped it. null on a completed reply.
usageobject
input_tokens (including any read from the cache, counted in input_tokens_details.cached_tokens), output_tokens (with output_tokens_details.reasoning_tokens when the model reports it) and total_tokens.

Streaming

With "stream": true, each event has an event: name and a data: line whose type matches it. The stream ends with response.completed, or response.incomplete when the reply was cut short. Either carries the whole response and its usage.

Events
event: response.created
data: {"type":"response.created","response":{"id":"resp_3c81f04d9a2b6e7105c4d8af","object":"response","created_at":1793270400,"status":"in_progress","incomplete_details":null,"model":"deepseek-v4.1-flash-1017-raw","output":[],"store":false}}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_3c81f04d9a2b6e7105c4d8af","object":"response","created_at":1793270400,"status":"in_progress","incomplete_details":null,"model":"deepseek-v4.1-flash-1017-raw","output":[],"store":false}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_a17e09c3d54b28f6e0913b7d","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_a17e09c3d54b28f6e0913b7d","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_a17e09c3d54b28f6e0913b7d","output_index":0,"content_index":0,"delta":"Rivers carry dissolved minerals from rocks into the sea,"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_a17e09c3d54b28f6e0913b7d","output_index":0,"content_index":0,"delta":" and when the water evaporates the salt stays behind."}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_a17e09c3d54b28f6e0913b7d","output_index":0,"content_index":0,"text":"Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind."}

event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_a17e09c3d54b28f6e0913b7d","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind."}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_a17e09c3d54b28f6e0913b7d","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind."}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_3c81f04d9a2b6e7105c4d8af","object":"response","created_at":1793270400,"status":"completed","incomplete_details":null,"model":"deepseek-v4.1-flash-1017-raw","output":[{"id":"msg_a17e09c3d54b28f6e0913b7d","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind."}]}],"store":false,"output_text":"Rivers carry dissolved minerals from rocks into the sea, and when the water evaporates the salt stays behind.","usage":{"input_tokens":21,"output_tokens":23,"total_tokens":44}}}
EventWhen
response.output_text.deltaEach piece of reply text.
response.reasoning_summary_text.deltaEach piece of the model’s reasoning, when it returns any.
response.function_call_arguments.deltaEach piece of a function call’s arguments, after a response.output_item.added naming the function.
response.output_item.doneAn output item is complete.
response.incompleteThe last event when the reply was cut short, in place of response.completed. Its response has status incomplete and the incomplete_details.
errorThe model failed part way through. It’s the last event. See Errors during a stream.

Events don’t carry a sequence_number. As with chat completions, a : keep-alive comment is sent after 15 seconds of silence.

With the OpenAI SDK’s responses.stream() helper, JavaScript’s finalResponse() returns an incomplete reply, but Python’s get_final_response() raises an error when the stream ends with response.incomplete. In Python, iterate over the events and read the last one’s response instead.

Not supported

Every request stands alone. Nothing is stored, so there’s nothing to refer back to.

FieldWhat happens
previous_response_idRefused with a 400. Send the earlier turns in input instead.
conversationRefused with a 400.
background: trueRefused with a 400. Use stream for long replies.
input_image with a file_idRefused with a 400. Use image_url.
input_file, audio and other partsRefused with a 400.
storeIgnored. Responses are never stored, and store is always false.