Skip to content

Responses API

The Responses API is OpenAI’s task-oriented interface: you send a model and input (plus optional generation and formatting fields), and receive a Response object—or a stream of events when stream is true. CompactifAI exposes this at POST /v1/responses for select deployed models.

Use it when your client library or product flow targets the Responses schema (for example the OpenAI SDK’s responses surface). For classic chat turns with messages, continue to use Chat completion (POST /v1/chat/completions).

Path POST /v1/responses
Base URL https://api.compactif.ai/v1/responses

Authenticate with a bearer token as described in Authentication.

Only model configuration ids that have the responses capability in your deployment can call this route. What you see in GET /v1/models and the models catalog is authoritative for your account.

Common ids include:

Model Model ID
Carina 60B carina-60b
GLM 5.2 glm-5-2
GLM 5.3 glm-5-3
Quasar 1.2 358B quasar-1-2-358b
Qwen 3.8 27B qwen-3-8-27b

If the model is missing, lacks responses support, or has no endpoint configured, the API returns 400 or 500 with guidance in detail.

  • model — Your CompactifAI model configuration id (mapped to the backend engine name on the wire).
  • input — A string or structured items (per the OpenAI Responses request shape). These items are accepted and ignored: compaction_trigger (the conversation is not compacted), item_reference (the referenced item is not looked up, so send its content inline or chain with previous_response_id), computer_call / computer_call_output, file_search_call, code_interpreter_call, image_generation_call, local_shell_call / local_shell_call_output, shell_call / shell_call_output, apply_patch_call / apply_patch_call_output, tool_search_call / tool_search_output, compaction, program / program_output, configuration_update and any item type not listed on this page. A request whose input holds only ignored items fails with error.code invalid_request and the message Input cannot be empty[<request id>], as the origin provider does. Without streaming it returns 400; with stream: true it returns 200 with a response.failed event followed by an error event, where <request id> is the response id without its resp_ prefix. custom_tool_call / custom_tool_call_output items reach the model as a function_call / function_call_output pair, with the free-form input sent as {"input": "..."}, when the input holds a user message, before or after them. An input with custom tool items and no user message fails the same way (400 without streaming, a response.failed and an error event when streaming), as the origin provider does. A replayed web_search_call reaches the model as an assistant message naming the queries and sources.
Field Notes
stream true returns SSE (text/event-stream) with data: JSON lines, ending with data: [DONE]. Default - false
max_output_tokens Caps generated tokens for this response. Use this field on Responses—not max_tokens (that belongs to chat completions).
background Accepted for compatibility. Responses always run synchronously: the result is returned in this call and nothing is queued.
prompt Accepted for compatibility and ignored. Hosted prompt templates ({"id": "...", "version": "...", "variables": {...}}) are not resolved: the field is dropped before the request reaches the model, and input and instructions are used as sent.
temperature, top_p Sampling controls. top_p: 0 selects greedy sampling: the gateway forwards temperature=0 and top_p=1, taking precedence over any temperature you also send.
previous_response_id Continues the conversation of a stored response. The response echoes it in previous_response_id, streamed and not streamed. A function_call_output can answer a function_call of that response by its call_id.
instructions High-level system-style instructions.
include Extra output data to return. Supported values: code_interpreter_call.outputs, computer_call_output.output.image_url, file_search_call.results, message.input_image.image_url, message.output_text.logprobs, reasoning.encrypted_content. With a web_search tool in tools, web_search_call.action.sources and web_search_call.results make the API run the search and return a web_search_call output item (see Web search). Any other value, or an include that is not an array, is ignored and has no effect on the response.
text, reasoning, metadata, truncation, parallel_tool_calls Same semantics as OpenAI Responses where your backend supports them.

Output items are named the same way streamed and not streamed: reasoning items rs_…, function calls fc_… with a call_id that starts with call_, messages msg_…. Within a stream, the item events, response.completed and the stored response (GET /v1/responses/{id}) carry the same ids.

Models whose reasoning is always on, for example glm-5-3, refuse a request that disables it (reasoning: {"effort": "none"}) with 400 and error.code reasoning_not_disableable. With stream: true the refusal is streamed instead: the response is 200 with a response.failed event, an error event carrying the same code and message, then data: [DONE].

See the full parameter table in the API reference → Responses API.

Add a web_search tool to tools and the model decides whether to search the web:

{
"model": "glm-5-3",
"input": "What is the latest stable Python release?",
"tools": [{"type": "web_search"}],
"include": ["web_search_call.action.sources", "web_search_call.results"]
}

When the model asks for a search, the API runs it, gives the results back to the model, and the model answers from them. It may search more than once, up to WEB_SEARCH_MAX_USES times per request (default 5). When the model does not search, for example for “Reply with OK.”, no search is run and output has no web_search_call.

Each search the model ran is a web_search_call item in output, in the order the model did things: its reasoning and message items stay in place between the searches (also streamed as response.web_search_call.in_progress, .searching and .completed):

  • action.type: "search" with action.queries / action.query: the search that was run.
  • action.sources: the result URLs, returned when include has web_search_call.action.sources.
  • results: title, snippet and url of each result, returned when include has web_search_call.results.
  • action.type: "open_page" with action.url: a page the model chose to read. The gateway fetches public pages only (the same rules as for search results). This needs page fetching on the deployment (WEB_SEARCH_FETCH_PAGES).

include only chooses which of those fields are returned; the search happens with or without it. A search or page read that failed is a web_search_call with status: "failed" and an error string, and the model is told it failed. tool_choice: "none" means no search; tool_choice: {"type": "web_search"} makes the model search first. filters.allowed_domains and user_location on the tool are honored. usage adds up every model call of the request, reasoning tokens included.

With stream: true the model’s events are relayed as they arrive. When the model calls the search, the stream pauses while the API runs it (announced by the response.web_search_call.* events), then continues with the model’s next turn in the same response; output_index and sequence_number run on across turns. If web search is not enabled on the deployment, the request succeeds without a search.

import requests
API_URL = "https://api.compactif.ai/v1/responses"
API_KEY = "your_api_key_here"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
data = {
"model": "carina-60b",
"input": "Say hello in five words.",
"max_output_tokens": 500,
}
response = requests.post(API_URL, headers=headers, json=data)
response.raise_for_status()
print(response.json())

Set "stream": true. Read the response body as Server-Sent Events: each meaningful line is data: followed by JSON (except the final data: [DONE] sentinel).

Terminal window
curl -N https://api.compactif.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"model":"carina-60b","input":"Say hello in one short sentence.","stream":true}'

Field-level support appears in OpenAI compatibility under the Responses tables (request and response fields). For exhaustive parameters and streaming details, use API reference → Responses API. Fields newer than the API’s Responses schema, such as reasoning.effort max or computer tools, are returned unchanged with 200; a 502 with error.code upstream_unavailable means the model provider is unavailable.