Responses
POST /v1/responses accepts the OpenAI Responses format, with or without streaming. Use client.responses of the openai SDK with the same base URL as Chat Completions. The endpoint is stateless: nothing is stored between requests.
Which models
This endpoint is for models whose API format column on Models & Pricing lists only OpenAI. A model that also lists Anthropic is generally not served here: the endpoint then answers400 and tells you to use /v1/chat/completions or /v1/messages. Not every OpenAI-format model offers the Responses format: one that does not gets the same 400, at no cost, so call that model through Chat Completions. Example request
curl https://octalabs.id/v1/responses \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "abliterated-large", "max_output_tokens": 256, "instructions": "Answer briefly.", "input": "Hi! Explain what an API is in one sentence." }'Stateless: send the whole conversation
Every request is processed with store: false. The id of a response is issued by us and names nothing a later request could refer to. That has three consequences:
store: true,previous_response_id,conversation,prompttemplates,background: trueanditem_referenceinput items are refused with400.- A response cannot be retrieved, listed, cancelled or deleted:
GETandDELETE /v1/responses/{id},/canceland/input_itemsanswer400. So do/v1/responses/input_tokensand/v1/responses/compact. - A conversation of several turns carries its own history: put the earlier turns in
inputwith every request.
A reasoning model keeps its line of thought only if its earlier reasoning comes back with the history. Ask for it with include: ["reasoning.encrypted_content"] and send the reasoning items back exactly as they were returned. A reasoning item without its encrypted_content is refused with 400.
Two turns · Python
history = [{"role": "user", "content": "Plan a three-day trip to Yogyakarta."}]first = client.responses.create( model="abliterated-large", input=history, include=["reasoning.encrypted_content"],)# Send back everything the model returned: messages, tool calls and reasoning items.history += first.outputhistory.append({"role": "user", "content": "Make day two cheaper."})second = client.responses.create( model="abliterated-large", input=history, include=["reasoning.encrypted_content"],)print(second.output_text)Supported fields
Yes means the field is honoured. Ignored means it is accepted and has no effect. Refused means the request is rejected with 400 before it runs, at no cost; error.param names the field and the message says why. A field that is not in this table is refused the same way. A field sent as null counts as not set.
| Field | Supported | Notes |
|---|---|---|
model | Yes | Required. |
input | Yes | Required. A string or a list of input items. See Input items below. |
instructions | Yes | A string. |
max_output_tokens | Yes | A positive integer no larger than the model’s context limit. It covers reasoning tokens and visible output together. |
stream | Yes | true for Server-Sent Events. |
stream_options | Yes | Only include_obfuscation. |
tools | Yes | Up to 128 function and custom tools. See Tools below. |
tool_choice | Yes | "none", "auto", "required", a named function or custom tool, or allowed_tools. |
parallel_tool_calls | Yes | |
reasoning | Yes | effort, summary, generate_summary and context. mode may only be "standard". |
text | Yes | format (including a JSON schema for structured output) and verbosity. |
include | Yes | reasoning.encrypted_content, message.output_text.logprobs and message.input_image.image_url. Other values return the output of built-in tools and are refused. |
temperaturetop_ptop_logprobs | Yes | |
truncation | Yes | |
image | Yes | Only context_compression. |
metadata | Yes | Returned in the response object. |
usersafety_identifierprompt_cache_key | Yes | |
store | Ignored | Only false. true is refused: responses are never stored. |
background | Ignored | Only false. true is refused: use stream for a long generation. |
service_tier | Ignored | Only "auto" or "default". Any other tier is refused. |
max_tool_calls | Ignored | It only limits built-in tools, and none are available. |
previous_response_idconversation | Refused | Responses are not stored. Send the whole conversation in input with every request. |
prompt | Refused | Stored prompt templates are not available. Send instructions and input. |
prompt_cache_retentionprompt_cache_options | Refused | Prompt cache settings cannot be chosen; the default applies. |
moderationaccess_programscontext_management | Refused |
Input items
input is a string or a list of these items. Items the API returned in output can be sent back as they are.
| Item | Notes |
|---|---|
message | Role user, assistant, system or developer. type may be left out. Content is a string or parts: input_text, input_image, and output_text or refusal for an assistant turn you send back. |
input_image part | image_url as a URL or a base64 data URL, with an optional detail. An uploaded file_id is refused. |
function_call, function_call_output | A call the model made to one of your function tools, and its result. The output is a string or input_text and input_image parts. |
custom_tool_call, custom_tool_call_output | The same for a custom tool. |
reasoning | Reasoning from an earlier turn. It must carry the encrypted_content it was returned with. |
File inputs (input_file), audio input (input_audio), item_reference and the items of built-in tools are refused with 400. Send file content as text or images.
Tools
Only tools that your application runs are available: function tools and custom tools. The model returns a function_call (or custom_tool_call) item; run the tool, then send the call and a function_call_output item with the same call_id in the next request.
The request after a tool call · JSON
{ "model": "abliterated-large", "max_output_tokens": 512, "tools": [{ "type": "function", "name": "get_weather", "description": "Get the current weather for a city.", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } }], "input": [ {"role": "user", "content": "What is the weather in Jakarta right now?"}, {"type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"Jakarta\"}"}, {"type": "function_call_output", "call_id": "call_1", "output": "{\"temp_c\": 31}"} ]}Every built-in tool is refused by name: web search, file search, code interpreter, image generation, computer use, MCP, shell and apply patch. They run on the provider’s side or are billed per call, outside the token usage a request is charged from.
Streaming
With "stream": true the reply is a stream of typed events, each with its own sequence_number. There is no [DONE] line: the stream ends after response.completed, response.incomplete, response.failed or error.
# -N turns off buffering so tokens appear as they arrivecurl -N https://octalabs.id/v1/responses \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "abliterated-large", "max_output_tokens": 256, "stream": true, "input": "Hello!" }'| Kind | Event types |
|---|---|
| Lifecycle | response.created, response.in_progress, response.completed, response.incomplete, response.failed |
| Output items | response.output_item.added, response.output_item.done, response.content_part.added, response.content_part.done |
| Text | response.output_text.delta, response.output_text.done, response.output_text.annotation.added, response.refusal.delta, response.refusal.done |
| Tool calls | response.function_call_arguments.delta, response.function_call_arguments.done, response.custom_tool_call_input.delta, response.custom_tool_call_input.done |
| Reasoning | response.reasoning_summary_part.added, response.reasoning_summary_part.done, response.reasoning_summary_text.delta, response.reasoning_summary_text.done, response.reasoning_text.delta, response.reasoning_text.done |
| Failure | error |
- Usage arrives once, in the
responseobject of the final event. - If the stream breaks before its final event, it ends with an
errorevent (codeserver_error). Such a stream reported no usage and is not charged. - While the model is quiet, a comment line
: keep-aliveis sent about every 15 seconds. The official SDK ignores it; a parser you write yourself must skip every line that starts with:. - The
x-billing-stateheader isstreaming, and the billing outcome is sent as the last SSE comment, as on the other endpoints.
A quiet moment and the end of the stream
event: response.output_text.deltadata: {"type":"response.output_text.delta","delta":"!","sequence_number":12,…}: keep-aliveevent: response.completeddata: {"type":"response.completed","response":{"id":"resp_…","status":"completed","usage":{…},…},"sequence_number":15}: x-billing-state settledThe response object
modelis the model ID you sent,idis our own (resp_…), andinstructionsis what you sent.statuscompletedis a finished reply.incompletemeans the model stopped early, for example atmax_output_tokens;incomplete_detailssays why. Both are charged from theirusage.statusfailedcarries anerrorwith a general code and message. It is charged only for the usage it reports, marked Partial on the Usage page.usage.input_tokensincludes cached tokens (input_tokens_details.cached_tokens, billed at the cache-read rate) andusage.output_tokensincludes reasoning tokens.
Output limit and hold
- Set
max_output_tokens. It bounds reasoning and visible output together, and it is what the output side of the hold is calculated from. - Without it, the hold covers the model’s whole context, which needs a much larger available balance.
- A request that contains an image or a
reasoningitem is held against the whole context on the input side. The final charge is still based on actual usage. See Billing & balance. - A reply without streaming has to be complete within 90 seconds; a stream only has to start within that time. See Limits & fields.
Response headers and error bodies are the same as on Chat Completions; errors use the OpenAI shape described in Errors & status codes.