Responses

POST /v1/responses is an OpenAI Responses API-compatible surface. It accepts an input value or input items, returns a response object, and supports SSE streaming with stream: true. Provider and model support is capability-driven, so check the catalog before selecting a model. Use Responses when you want the newer item-based output format, built-in tools, reasoning controls, or a single request shape that can grow beyond a simple chat transcript.

Quick start

curl -X POST "https://api.llmapi.ai/v1/responses" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Give me three names for a coffee shop."
  }'

For streaming, add "stream": true and consume the response as SSE events. Responses can also carry tools, structured outputs, reasoning controls, and web-search tools where the selected model supports them.

Response shape

Unlike Chat Completions, a response places generated items in output. A text message normally contains an output_text content item. Some models also return reasoning, tool calls, or tool results as separate output items.

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-4o-mini",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Here are three names..." }]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 10,
    "total_tokens": 24
  }
}

When writing a generic client, iterate over output and collect text items; do not assume the first output item is a message.

Input and common fields

Field	Description
`model`	Model ID or a `provider/model` name. The catalog determines whether the model supports Responses.
`input`	A string, an array of input messages/items, or multimodal content supported by the model.
`instructions`	Optional high-level instruction analogous to a system message.
`max_output_tokens`	Maximum number of output tokens. Chat Completions uses `max_tokens` instead.
`stream`	Return response lifecycle events over SSE.
`tools`, `tool_choice`	Enable supported built-in or function tools.
`reasoning`	Configure reasoning effort or summaries on compatible reasoning models.
`text` / `response_format`	Request plain text or structured output where supported.
`prompt_cache_key`, `prompt_cache_options`	OpenAI prompt caching, passed through unchanged; see prompt caching.

For a multi-turn request, pass an array of input items. Keep the item format consistent with the OpenAI Responses API.

Tools and structured output

Responses can be used for agent-style calls when the selected model advertises tool support. A function tool definition is sent in tools; if the model emits a function call, execute it in your application and send the resulting tool output in the next request. Tool execution is not performed by LLM API.

{
  "model": "gpt-4o-mini",
  "input": "What is the weather in Kyiv?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  ]
}

Structured output and built-in web search are also capability-dependent. See Reasoning, Web Search, and Response Healing for gateway-specific details.

Streaming and retrieval

With stream: true, consume the SSE lifecycle events until the response is complete. Text deltas are emitted as response output-text events; tool calls and reasoning can appear as different event types. Treat event types as an extensible protocol and ignore fields your client does not use.

curl -N -X POST "https://api.llmapi.ai/v1/responses" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Stream a short explanation of embeddings.",
    "stream": true
  }'

Notes

Use input and max_output_tokens; Chat Completions requests instead use messages and max_tokens.
GET /v1/responses/{response_id} is exposed for compatibility, but response objects are not stored for retrieval by default. Save the POST response in your application when you need it later; a lookup may return 404.
The gateway normalizes the request and routes it to a compatible provider; it does not execute function tools on your behalf.
Use X-LLMAPI-Region: eu, us, ap, or global to select a canonical region for providers that support multi-region routing.
See the OpenAI Responses API reference, Reasoning, Web Search, and Response Healing.