Create Response

POST /v1/responses Models: Chat and reasoning View .md

Create an OpenAI-compatible response. reasoning.effort maps through the selected model's reasoning_config when configured. reasoning.max_tokens caps thinking tokens when the model advertises reasoning.supports_max_tokens: true in /v1/models?format=openrouter (a max_tokens property under the reasoning parameter in the default list); other models accept the budget without enforcing it. reasoning.context and reasoning.mode are accepted but ignored. The :express model variant derives a budget for models with enforced budget support when no budget is supplied.

Response shape: Responses follow OpenAI's Responses API object whichever engine serves the model, with the fields OpenRouter's SDKs require always present: completed_at is a unix timestamp once the response has finished, error is null or {code, message}, and text is an object. Function call ids start with call_, and engine-internal fields (kv_transfer_params, input_messages, output_messages, ...) are removed from the response and from every streamed event.

Tools: function, custom and namespace tools, as Codex CLI sends them. A custom tool's call is a custom_tool_call item whose input is the raw text; its format grammar is described to the model, not enforced. A call to a tool of a namespace is a function_call with namespace set. Hosted tools (web_search, file_search, code_interpreter, mcp, ...) are refused with a 400 naming the type.

Stored responses: Nothing is stored. store is accepted and ignored. previous_response_id, conversation and background: true are refused with a 400; send the whole conversation in input. GET and DELETE on /v1/responses/{id} answer a 404 saying so.

Context window: If input plus max_output_tokens passes the model's context length, max_output_tokens is reduced to fit; if the input alone does not fit the request is a 400 with metadata.error_type context_length_exceeded.

Errors: Errors use OpenRouter's envelope, {"error": {"code", "message", "type", "metadata": {"error_type"}}}. A streaming request that fails before the first event gets the real HTTP status and the JSON envelope; one that fails later ends the stream with an error event and a response.failed event.

Body

application/json

OpenAI's Responses request. Fields not listed here are passed to the engine. store is accepted and ignored: nothing is stored.

model string

If omitted, the gateway resolves its default model. A :<variant> suffix is parsed separately from the model ID; :express derives a thinking budget when the model supports enforced budgets and no explicit budget is supplied.
input string or array of objects required

Input text or structured input items. A message item's content may hold input_text, input_image and input_file parts. An input_file ({"type": "input_file", "filename": "report.pdf", "file_data": "data:application/pdf;base64,..."}, or file_url in place of file_data) is converted to text before the model sees it, with the types, limits, token counting, caching and errors described under chat-content-part. file_id (a file uploaded with POST /files) uses its stored text.
One of 2
- string
- array of objects
instructions string

A system prompt.
max_output_tokens integer

Maximum output tokens, including reasoning and visible output. Reduced to fit the model's context window with the input.

default 32768at least 1
temperature number

range 0–2
top_p number

range 0–1
tools array of objects

function, custom and namespace tools. Any other type (hosted tools such as web_search) is refused with a 400 naming it.
7 fields
- type string required
  
  functioncustomnamespace
- name string required
- description string
- parameters object
  
  A function tool's arguments, as a JSON schema.
- strict boolean
- format object
  
  A custom tool's input: {"type": "text"} (the default) or {"type": "grammar", "syntax": "lark" or "regex", "definition": "..."}. The grammar is described to the model; the engine does not enforce it.
- tools array of objects
  
  A namespace tool's function tools. A call to one comes back as a function_call with namespace set.
tool_choice string or object

none, auto, required, or a specific function or custom tool. Anything but none needs tools.
One of 2
- string
- object
  - type string required
    
    functioncustom
  - name string required
reasoning object

Reasoning controls. Configured models map effort through their database profile. Models advertising reasoning.supports_max_tokens: true in /v1/models?format=openrouter (a max_tokens property under the reasoning parameter in the default list) enforce the budget; other models accept it without enforcing it.
4 fields
- effort string
  
  ultramaxxhighhighmediumlowminimalnone
- enabled boolean
  
  When false, sets effort to none.
- summary string
  
  Accepted but not supported by the current engines.
  
  autoconcisedetailed
- max_tokens integer
  
  Thinking-token budget. Must be below the effective completion limit so the model has room to answer. Ignored when thinking is disabled or a final assistant message is being continued.
  
  at least 1
store boolean

Accepted and ignored. Nothing is stored, whatever the value.
previous_response_id string or null

Refused with a 400 unless null. Responses are not stored; send the whole conversation in input.
conversation any

Refused with a 400. Conversations are not stored.
background boolean

true is refused with a 400. A background response would have to be stored to be retrieved.
stream boolean

Responses

application/json, text/event-stream · response-create-response-payload

15 fields

id string required

resp_ followed by hex characters. The response is not stored.
object string required

response
created_at integer required
completed_at integer or null required

Unix time the response finished; null while it is in progress.
status string required

completedincompletefailedin_progresscancelledqueued
error object or null required

Why a response failed; null otherwise.
2 fields
- code string
- message string
incomplete_details object or null
1 field
- reason string
  
  max_output_tokens when the output budget ran out.
model string required
output array of objects required

message, reasoning, function_call and custom_tool_call items. A call's call_id starts with call_; a call to a tool of a namespace carries namespace.
store boolean

Always false.
previous_response_id string or null

Always null.
text object required

The text format; {"format": {"type": "text"}} by default.
tool_choice any

Echoes the request's, auto when none was sent.
tools array of objects
usage object or null required
5 fields
- input_tokens integer
- input_tokens_details object
  2 fields
  - cached_tokens integer
  - cache_write_tokens integer
- output_tokens integer
  
  Includes reasoning tokens.
- output_tokens_details object
  1 field
  - reasoning_tokens integer
- total_tokens integer

curl https://api.vultrinference.com/v1/responses \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "instructions": "Answer in one sentence.",
    "input": "Why is the sky blue?",
    "max_output_tokens": 512
  }'

import os
import requests

response = requests.post(
    "https://api.vultrinference.com/v1/responses",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
    json={
        "model": "deepseek-v4.1-flash",
        "instructions": "Answer in one sentence.",
        "input": "Why is the sky blue?",
        "max_output_tokens": 512,
    },
)
print(response.json())

const response = await fetch("https://api.vultrinference.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "deepseek-v4.1-flash",
    "instructions": "Answer in one sentence.",
    "input": "Why is the sky blue?",
    "max_output_tokens": 512
  }),
});
console.log(await response.json());

Response · 200

{
    "id": "string",
    "object": "response",
    "created_at": 1790000000,
    "completed_at": 1790000000,
    "status": "completed",
    "error": {
        "code": "string",
        "message": "string"
    },
    "model": "string",
    "output": [
        {}
    ],
    "text": {},
    "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
            "cached_tokens": 0,
            "cache_write_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 0
    }
}