---
title: "Create a model response"
method: POST
path: "/responses"
tags: ["Responses"]
---

# Create a model response

`POST /responses`

Creates a model response using the OpenAI-compatible Responses API.
The request accepts either a single text input or a list of input
items (allowing batched, multi-turn input in one request), and the
result can be streamed to the client as it is generated.

Not every provider implements the Responses API. Requests routed to a
provider that does not support it return `400 Bad Request` with an
explanatory error message; use `/chat/completions` for those providers.

## Query parameters

- `provider` 'ollama' | 'ollama_cloud' | 'groq' | 'llamacpp' | 'openai' | 'cloudflare' | 'cohere' | 'anthropic' | 'deepseek' | 'google' | 'mistral' | 'minimax' | 'moonshot' | 'nvidia' | 'zai'

## Request body

- CreateResponseRequest — Request body for creating a model response via the Responses API.
  - `model` string, required — Model ID used to generate the response.
  - `input` union, required — Text, image, or file inputs to the model. Either a single text prompt or a list of input items representing a (possibly batched) conversation.
    - string — A text input to the model, equivalent to a user message.
    - ResponseInputItem[] — A list of input items.
      - `type` string — The type of the input item. Defaults to `message`.
      - `role` 'user' | 'assistant' | 'system' | 'developer', required — The role of the message input.
      - `content` union, required — Text or multimodal content for an input message. Either a string or a list of content parts.
        - string — A text input to the model.
        - ResponseInputContentPart[]
          - union — A content part within an input message.
            - object — A text input to the model.
              - …
            - object — An image input to the model.
              - …
  - `instructions` string, nullable — A system (or developer) message inserted into the model's context. When used with `previous_response_id`, instructions from previous responses are not carried over.
  - `max_output_tokens` integer, nullable — An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
  - `stream` boolean — If set to true, the model response data is streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
  - `temperature` number, float, nullable — What sampling temperature to use, between 0 and 2. Higher values make the output more random; lower values make it more focused.
  - `top_p` number, float, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the tokens with `top_p` probability mass.
  - `tools` ResponseTool[] — An array of tools the model may call while generating a response.
    - `type` 'function', required — The type of the tool. Currently only `function`.
    - `name` string, required — The name of the function to call.
    - `description` string — A description of the function, used by the model to decide when and how to call it.
    - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.
    - `strict` boolean — Whether to enforce strict parameter validation.
  - `tool_choice` union — How the model should select which tool (or tools) to use. Either a mode string (`none`, `auto`, `required`) or an object forcing a specific tool.
    - 'none' | 'auto' | 'required' — The tool-choice mode.
    - object — Forces the model to call a specific function tool.
      - `type` 'function', required
      - `name` string, required
  - `reasoning` ResponseReasoning — Configuration options for reasoning models.
    - `effort` 'minimal' | 'low' | 'medium' | 'high', nullable — Constrains the effort on reasoning for reasoning models. Reducing effort can result in faster responses and fewer reasoning tokens.
    - `summary` 'auto' | 'concise' | 'detailed', nullable — A summary of the reasoning performed by the model, useful for debugging and understanding the model's reasoning process.
  - `text` ResponseTextConfig — Configuration options for a text response from the model. Can be plain text or structured JSON data.
    - `format` object — An object specifying the format that the model must output.
      - `type` 'text' | 'json_schema' | 'json_object', required — The type of response format being defined.
      - `name` string — The name of the response format (used with `json_schema`).
      - `schema` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.
      - `strict` boolean — Whether to enable strict schema adherence.
  - `previous_response_id` string, nullable — The unique ID of the previous response to the model. Use this to create multi-turn conversations.
  - `store` boolean — Whether to store the generated model response for later retrieval.
  - `background` boolean — Whether to run the model response in the background. Useful for long-running or batched requests.
  - `parallel_tool_calls` boolean — Whether to allow the model to run tool calls in parallel.
  - `metadata` object — Set of up to 16 key-value pairs that can be attached to the object and returned when retrieving the response.
  - `user` string — A stable identifier for your end-users, used to help detect and prevent abuse.

## Response `200`

Successful response

- Response — Represents a model response returned by the Responses API.
  - `id` string, required — Unique identifier for this response.
  - `object` string, required — The object type, which is always `response`.
  - `created_at` integer, required — Unix timestamp (in seconds) of when the response was created.
  - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete', required — The status of the response generation.
  - `model` string, required — The model used to generate the response.
  - `output` ResponseOutputItem[], required — An array of content items generated by the model.
    - union — An output item generated by the model: an output message, a function tool call, or a reasoning item.
      - object — An output message from the model.
        - `type` 'message', required — The type of the output item. Always `message`.
        - `id` string, required — The unique ID of the output message.
        - `role` 'assistant', required — The role of the output message. Always `assistant`.
        - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the message.
        - `content` ResponseOutputContent[], required
          - union — A content part of an output message.
            - object — A text output from the model.
              - …
            - object — A refusal generated by the model.
              - …
      - object — A tool call to a function generated by the model.
        - `type` 'function_call', required — The type of the output item. Always `function_call`.
        - `id` string — The unique ID of the function tool call.
        - `call_id` string, required — The unique ID of the function tool call generated by the model, used to associate the call with its output.
        - `name` string, required — The name of the function to run.
        - `arguments` string, required — A JSON string of the arguments to pass to the function.
        - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the function tool call.
      - object — A reasoning item describing the model's chain of thought.
        - `type` 'reasoning', required — The type of the output item. Always `reasoning`.
        - `id` string, required — The unique ID of the reasoning item.
        - `summary` ResponseReasoningSummaryPart[], required — Reasoning summary content.
          - `type` 'summary_text', required — The type of the summary. Always `summary_text`.
          - `text` string, required — A summary of the reasoning output from the model.
        - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the reasoning item.
  - `error` ResponseError, nullable — An error object returned when the model fails to generate a response.
    - `code` string, required — The error code for the response.
    - `message` string, required — A human-readable description of the error.
  - `incomplete_details` ResponseIncompleteDetails, nullable — Details about why the response is incomplete.
    - `reason` string — The reason why the response is incomplete.
  - `instructions` string, nullable — The system/developer message used to generate the response.
  - `max_output_tokens` integer, nullable — An upper bound for the number of generated tokens.
  - `previous_response_id` string, nullable — The unique ID of the previous response, if any.
  - `reasoning` ResponseReasoning — Configuration options for reasoning models.
    - `effort` 'minimal' | 'low' | 'medium' | 'high', nullable — Constrains the effort on reasoning for reasoning models. Reducing effort can result in faster responses and fewer reasoning tokens.
    - `summary` 'auto' | 'concise' | 'detailed', nullable — A summary of the reasoning performed by the model, useful for debugging and understanding the model's reasoning process.
  - `temperature` number, float, nullable
  - `top_p` number, float, nullable
  - `tool_choice` union — How the model should select which tool (or tools) to use. Either a mode string (`none`, `auto`, `required`) or an object forcing a specific tool.
    - 'none' | 'auto' | 'required' — The tool-choice mode.
    - object — Forces the model to call a specific function tool.
      - `type` 'function', required
      - `name` string, required
  - `tools` ResponseTool[]
    - `type` 'function', required — The type of the tool. Currently only `function`.
    - `name` string, required — The name of the function to call.
    - `description` string — A description of the function, used by the model to decide when and how to call it.
    - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.
    - `strict` boolean — Whether to enforce strict parameter validation.
  - `text` ResponseTextConfig — Configuration options for a text response from the model. Can be plain text or structured JSON data.
    - `format` object — An object specifying the format that the model must output.
      - `type` 'text' | 'json_schema' | 'json_object', required — The type of response format being defined.
      - `name` string — The name of the response format (used with `json_schema`).
      - `schema` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.
      - `strict` boolean — Whether to enable strict schema adherence.
  - `metadata` object
  - `usage` ResponseUsage — Token usage details for the response.
    - `input_tokens` integer, required — The number of input tokens.
    - `input_tokens_details` object — A detailed breakdown of the input tokens.
      - `cached_tokens` integer — The number of tokens retrieved from the cache.
    - `output_tokens` integer, required — The number of output tokens.
    - `output_tokens_details` object — A detailed breakdown of the output tokens.
      - `reasoning_tokens` integer — The number of reasoning tokens.
    - `total_tokens` integer, required — The total number of tokens used (input + output).

## Other responses

- `400` — The selected provider does not implement the Responses API. The gateway returns this when a request is routed to a provider without Responses support.
- `401` — Unauthorized
- `500` — Internal server error

## Changes

- **2026-07-18** `b8f52abd9b46` — 1 info
  - added the new enum value `llamacpp` to the `query` request parameter `provider`
- **2026-07-08** `cf6fa75bd93f` — 1 info
  - endpoint added
- **2025-07-25** `70bffe5f3ff6` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/changes/responses/post.md)

---

[API](https://skmtc.dev/inference-gateway/apis/inference-gateway-api.md) · [All operations](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inference-gateway/inference-gateway-api/revisions/fccc79b863aa/schema)