API reference
Responses
POST /v1/responses takes a request in the OpenAI Responses format. Every request stands alone: nothing is stored between calls.
https://gateway.kalsenti.ai/v1/responsesOn 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" }, withminimal,low,mediumorhigh. Models that don’t reason ignore it.textobjecttext.formatasks for structured output. Models that can’t do it refuse the request with a400.
Other fields are ignored. store is always treated as false.
Input items
- Messages, with a
roleofsystem,developer,userorassistant. Theircontentis a string or a list ofinput_text,output_textandinput_imageparts. An image is given by itsimage_url: a web address or a base64data:URL. function_callitems the model made earlier, and yourfunction_call_outputitems answering them bycall_id.reasoningitems from an earlier reply, which are passed back when they carryencrypted_content.
Other item types are skipped. As nothing is stored between requests, send the whole conversation each time:
"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
{
"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:
reasoningitems with asummary,messageitems withoutput_textcontent, andfunction_callitems with acall_id,nameandarguments. output_textstring- All the reply’s text in one string.
statusstringcompleted, orincompletewhen the reply was cut short. The last output item is thenincompletetoo.incomplete_detailsobject or null- Why an incomplete reply stopped:
{ "reason": "max_output_tokens" }when it reachedmax_output_tokens, or{ "reason": "content_filter" }when the model’s host stopped it.nullon a completed reply. usageobjectinput_tokens(including any read from the cache, counted ininput_tokens_details.cached_tokens),output_tokens(withoutput_tokens_details.reasoning_tokenswhen the model reports it) andtotal_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.
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}}}| Event | When |
|---|---|
response.output_text.delta | Each piece of reply text. |
response.reasoning_summary_text.delta | Each piece of the model’s reasoning, when it returns any. |
response.function_call_arguments.delta | Each piece of a function call’s arguments, after a response.output_item.added naming the function. |
response.output_item.done | An output item is complete. |
response.incomplete | The last event when the reply was cut short, in place of response.completed. Its response has status incomplete and the incomplete_details. |
error | The 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.
| Field | What happens |
|---|---|
previous_response_id | Refused with a 400. Send the earlier turns in input instead. |
conversation | Refused with a 400. |
background: true | Refused with a 400. Use stream for long replies. |
input_image with a file_id | Refused with a 400. Use image_url. |
input_file, audio and other parts | Refused with a 400. |
store | Ignored. Responses are never stored, and store is always false. |