Skip to main content

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 answers 400 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, prompt templates, background: true and item_reference input items are refused with 400.
  • A response cannot be retrieved, listed, cancelled or deleted: GET and DELETE /v1/responses/{id}, /cancel and /input_items answer 400. So do /v1/responses/input_tokens and /v1/responses/compact.
  • A conversation of several turns carries its own history: put the earlier turns in input with 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
modelYesRequired.
inputYesRequired. A string or a list of input items. See Input items below.
instructionsYesA string.
max_output_tokensYesA positive integer no larger than the model’s context limit. It covers reasoning tokens and visible output together.
streamYestrue for Server-Sent Events.
stream_optionsYesOnly include_obfuscation.
toolsYesUp to 128 function and custom tools. See Tools below.
tool_choiceYes"none", "auto", "required", a named function or custom tool, or allowed_tools.
parallel_tool_callsYes
reasoningYeseffort, summary, generate_summary and context. mode may only be "standard".
textYesformat (including a JSON schema for structured output) and verbosity.
includeYesreasoning.encrypted_content, message.output_text.logprobs and message.input_image.image_url. Other values return the output of built-in tools and are refused.
temperature
top_p
top_logprobs
Yes
truncationYes
imageYesOnly context_compression.
metadataYesReturned in the response object.
user
safety_identifier
prompt_cache_key
Yes
storeIgnoredOnly false. true is refused: responses are never stored.
backgroundIgnoredOnly false. true is refused: use stream for a long generation.
service_tierIgnoredOnly "auto" or "default". Any other tier is refused.
max_tool_callsIgnoredIt only limits built-in tools, and none are available.
previous_response_id
conversation
RefusedResponses are not stored. Send the whole conversation in input with every request.
promptRefusedStored prompt templates are not available. Send instructions and input.
prompt_cache_retention
prompt_cache_options
RefusedPrompt cache settings cannot be chosen; the default applies.
moderation
access_programs
context_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
messageRole 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 partimage_url as a URL or a base64 data URL, with an optional detail. An uploaded file_id is refused.
function_call, function_call_outputA 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_outputThe same for a custom tool.
reasoningReasoning 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
Lifecycleresponse.created, response.in_progress, response.completed, response.incomplete, response.failed
Output itemsresponse.output_item.added, response.output_item.done, response.content_part.added, response.content_part.done
Textresponse.output_text.delta, response.output_text.done, response.output_text.annotation.added, response.refusal.delta, response.refusal.done
Tool callsresponse.function_call_arguments.delta, response.function_call_arguments.done, response.custom_tool_call_input.delta, response.custom_tool_call_input.done
Reasoningresponse.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
Failureerror
  • Usage arrives once, in the response object of the final event.
  • If the stream breaks before its final event, it ends with an error event (code server_error). Such a stream reported no usage and is not charged.
  • While the model is quiet, a comment line : keep-alive is 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-state header is streaming, 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 settled

The response object

  • model is the model ID you sent, id is our own (resp_…), and instructions is what you sent.
  • status completed is a finished reply. incomplete means the model stopped early, for example at max_output_tokens; incomplete_details says why. Both are charged from their usage.
  • status failed carries an error with a general code and message. It is charged only for the usage it reports, marked Partial on the Usage page.
  • usage.input_tokens includes cached tokens (input_tokens_details.cached_tokens, billed at the cache-read rate) and usage.output_tokens includes 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 reasoning item 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.

Start with any balance,
however small.

Create a free accountSign in AI API · pay as you go