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).
Endpoint
Section titled “Endpoint”| Path | POST /v1/responses |
| Base URL | https://api.compactif.ai/v1/responses |
Authenticate with a bearer token as described in Authentication.
Eligible models
Section titled “Eligible models”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.
Required fields
Section titled “Required fields”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 withprevious_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_updateand any item type not listed on this page. A request whose input holds only ignored items fails witherror.codeinvalid_requestand the messageInput cannot be empty[<request id>], as the origin provider does. Without streaming it returns400; withstream: trueit returns200with aresponse.failedevent followed by anerrorevent, where<request id>is the response id without itsresp_prefix.custom_tool_call/custom_tool_call_outputitems reach the model as afunction_call/function_call_outputpair, 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 (400without streaming, aresponse.failedand anerrorevent when streaming), as the origin provider does. A replayedweb_search_callreaches the model as an assistant message naming the queries and sources.
Common optional fields
Section titled “Common optional fields”| 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.
Web search
Section titled “Web search”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"withaction.queries/action.query: the search that was run.action.sources: the result URLs, returned whenincludehasweb_search_call.action.sources.results:title,snippetandurlof each result, returned whenincludehasweb_search_call.results.action.type: "open_page"withaction.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.
Non-streaming example
Section titled “Non-streaming example”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())Streaming example
Section titled “Streaming example”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).
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}'Compatibility and reference
Section titled “Compatibility and reference”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.