Responses


POST /api/v1/responses

OpenAI Responses format. Works with every model in the catalog via any-to-any translation.

Request body

Body — application/json (required)

modelstringrequired

Model slug to invoke (e.g. deepseek/deepseek-v4-pro).

inputstring | (message | function_call | function_call_output | reasoning)[]required

Conversation input: a shorthand string or an array of input items.

Show 2 variants

stringstring

Show 4 variants

messageobject

Show 3 nested fields

type"message"

Item type discriminator (message).

rolestringrequired

Conversation role. `developer` maps to `system`.

Possible values: system developer user assistant

contentstring | (input_text | output_text | input_image | input_file)[]required

Message content: a string or an array of input/output parts.

Show 2 variants

stringstring

Show 4 variants

input_textobject

Show 2 nested fields

type"input_text"required

textstringrequired

The user text content.

output_textobject

Show 2 nested fields

type"output_text"required

textstringrequired

Prior assistant text content.

input_imageobject

Show 3 nested fields

type"input_image"required

image_urlstringrequired

Image URL or data: URL.

detailstring

OpenAI vision detail level (low/high/auto).

input_fileobject

Show 4 nested fields

type"input_file"required

filenamestring

Optional filename hint.

file_datastring

File contents as a data: URL.

file_urlstring

File contents as a fetchable URL.

function_callobject

Show 4 nested fields

type"function_call"required

call_idstringrequired

Tool call id.

namestringrequired

Function name.

argumentsstringrequired

JSON-encoded arguments string.

function_call_outputobject

Show 3 nested fields

type"function_call_output"required

call_idstringrequired

Tool call id this output answers.

outputstringrequired

Tool result output (string).

reasoningobject

Show 2 nested fields

type"reasoning"required

summaryobject[]

Reasoning summary blocks.

Default: []

Show 2 nested fields

type"summary_text"required

textstringrequired

Reasoning summary text.

instructionsstring | null

Top-level system instructions (alternative to a system message).

tools(function | object | object | object)[]

Function tools, built-in server tools, OpenAI hosted tools, and/or OpenRouter server tools (024-R26).

Show 4 variants

functionobject

Show 5 nested fields

type"function"required

namestringrequired

Function name.

descriptionstring | null

Natural-language description for the model.

parametersobject | null

JSON Schema for the function arguments.

strictboolean | null

Enable OpenAI strict structured outputs.

objectobject

Show 3 nested fields

typestringrequired

Built-in server tool id (002-R11).

Possible values: web_search web_fetch pdf datetime image

eventsboolean

Opt this tool into `hi.tool_event` streaming (009-R55).

max_usesinteger

Max invocations of this tool in the request (018). Default 1000.

objectobject

Show 6 nested fields

typestringrequired

OpenAI Responses hosted tool type (web_search_preview|file_search|code_interpreter|...).

search_context_sizestring

Possible values: low medium high

user_locationobject

filtersobject

vector_store_idsstring[]

containerany

objectobject

Show 4 nested fields

typestringrequired

OpenRouter server tool id (openrouter:web_search|...).

parametersobject

max_usesinteger

eventsboolean

tool_choicestring | function

How to choose tools: auto, none, required, or a specific function.

Show 2 variants

stringstring

Possible values: auto none required

functionobject

Show 2 nested fields

type"function"required

namestringrequired

Function name to force.

parallel_tool_callsboolean | null

Allow the model to call tools in parallel.

max_tool_callsinteger | null

Max total tool calls in the request.

max_output_tokensinteger | null

Max output tokens.

temperaturenumber | null

Sampling temperature, 0–2.

top_pnumber | null

Nucleus sampling probability, 0–1.

top_logprobsinteger | null

Top-N log probabilities per token.

includestring[]

Derived fields to include (e.g. message.output_text.logprobs).

frequency_penaltynumber | null

Penalize tokens by frequency, -2 to 2.

presence_penaltynumber | null

Penalize tokens by presence, -2 to 2.

logit_biasmap<string, number> | null

Token-id → bias map.

seedinteger | null

Sampling seed for best-effort determinism.

streamboolean

Stream SSE events instead of returning one object.

textobject

Text output formatting (response format + verbosity).

Show 2 nested fields

formatobject

Force text, JSON, or a specific JSON Schema on the output.

Show 4 nested fields

typestringrequired

Response format mode.

Possible values: text json_object json_schema

namestring

Schema name.

schemaobject

JSON Schema describing the response.

strictboolean

Enable strict structured outputs.

verbositystring

Output verbosity dial.

Possible values: low medium high xhigh max

reasoningobject | null

Reasoning controls (effort + summary).

Show 2 nested fields

effortstring | null

Possible values: none minimal low medium high xhigh max

summarystring | null

Reasoning-summary verbosity (auto|concise|detailed) — accepted and ignored.

previous_response_idstring | null

Not supported — the gateway is stateless. Rejected explicitly.

storeboolean

Not supported (stateless) — rejected when true.

backgroundboolean

Not supported (stateless) — rejected when true.

conversationstring | object | null

Not supported (stateless) — rejected when set.

promptobject | null

Not supported (stateless) — rejected when set.

service_tierstring | null

OpenAI service tier — accepted but the gateway owns tiering.

userstring | null

End-user identifier for abuse monitoring.

safety_identifierstring | null

Alternate end-user identifier (maps to `user`).

hi_tool_eventsboolean

Opt the whole request into `hi.tool_event` streaming (009-R55).

Generated at build time from the API's OpenAPI document — the same schemas that validate requests, so this section cannot drift from the API.

input accepts plain text or a list of input items. stream: true switches to the semantic SSE event protocol — see Streaming. This endpoint is stateless: previous_response_id is rejected — send the full input. Server tools activate as built-in tool types in tools — see server tools.

Stop sequences are not expressible in this format and are rejected as invalid_request — see the capability gaps.

Response


{
  "id": "resp_def456",
  "object": "response",
  "created_at": 1767312000,
  "status": "completed",
  "model": "anthropic/claude-sonnet-4.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Speculative decoding drafts tokens…" }]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 34,
    "total_tokens": 55,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens_details": { "reasoning_tokens": 0 }
  }
}

Reasoning models emit reasoning output items ahead of the message. The id is resp_<request id> — pass the request ID (also returned in the X-Request-Id header) to GET /generation.

Response schema

200Response

The response object. With `stream: true`, an SSE stream instead.

application/json

idstringrequired

resp_<request id>.

object"response"required

created_atintegerrequired

Unix seconds.

statusstringrequired

Possible values: completed incomplete

incomplete_detailsobject | null

Show 1 nested field

reasonstring

Possible values: max_output_tokens content_filter

modelstringrequired

outputobject[]required

Output items in order: optional `reasoning` (summary_text), `message` (output_text content), and one `function_call` per tool call.

usageobjectrequired

Show 5 nested fields

input_tokensinteger

input_tokens_detailsobject

Show 2 nested fields

cached_tokensinteger

audio_tokensinteger

Audio input tokens; omitted when 0.

output_tokensinteger

output_tokens_detailsobject

Show 2 nested fields

reasoning_tokensinteger

audio_tokensinteger

Audio output tokens; omitted when 0.

total_tokensinteger

text/event-streamSSE stream

Semantic SSE event protocol (`event:` + `data:` frames): `response.created` / `response.in_progress`, then per-item events (`response.output_item.added`, `response.output_text.delta`, `response.function_call_arguments.delta`, matching `*.done` events), ending with `response.completed` carrying the full response incl. usage (002-R8). Keep-alive comments every 15 s.

errorError envelope (any non-2xx status)

Error in this ingress format's native envelope, with the stable taxonomy `code` (002-R7). See the ErrorCode schema for the code → HTTP status mapping.

errorobjectrequired

Show 6 nested fields

messagestringrequired

typestringrequired

OpenAI-compatible error class (e.g. invalid_request_error).

codestringrequired

Stable error taxonomy (002-R7), identical across ingress formats. HTTP status per code: provider_auth=502, provider_rate_limit=429, provider_overloaded=529, context_length_exceeded=400, content_filter=400, provider_timeout=504, provider_unavailable=502, insufficient_credits=402, key_limit_exceeded=402, model_not_allowed=403, invalid_api_key=401, workspace_locked=403, rate_limit_exceeded=429, invalid_request=400, payload_too_large=413, internal_error=500.

Possible values: provider_auth provider_rate_limit provider_overloaded context_length_exceeded content_filter provider_timeout provider_unavailable insufficient_credits key_limit_exceeded model_not_allowed invalid_api_key workspace_locked rate_limit_exceeded invalid_request payload_too_large internal_error

paramstring | null

request_idstring

retry_after_secondsinteger

Seconds until the request can be retried (clamped to 1–120). Present iff a Retry-After HTTP header is also set — on rate_limit_exceeded (429), provider_rate_limit (429), provider_overloaded (529), provider_timeout (504), and provider_unavailable (502). Absent on all other errors.

Generated at build time from the API's OpenAPI document — the same schemas that validate requests, so this section cannot drift from the API.

Examples

curl


curl https://api.hyperinfer.ai/api/v1/responses \
  -H "Authorization: Bearer $HYPERINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "instructions": "You are a concise assistant.",
    "input": "In one sentence: what is speculative decoding?",
    "max_output_tokens": 256
  }'

TypeScript


import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "https://api.hyperinfer.ai/api/v1",
  apiKey: process.env.HYPERINFER_API_KEY,
});
 
const response = await client.responses.create({
  model: "anthropic/claude-sonnet-4.5",
  instructions: "You are a concise assistant.",
  input: "In one sentence: what is speculative decoding?",
  max_output_tokens: 256,
});
 
console.log(response.output_text);

Python


import os
from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.hyperinfer.ai/api/v1",
    api_key=os.environ["HYPERINFER_API_KEY"],
)
 
response = client.responses.create(
    model="anthropic/claude-sonnet-4.5",
    instructions="You are a concise assistant.",
    input="In one sentence: what is speculative decoding?",
    max_output_tokens=256,
)
 
print(response.output_text)

Errors

OpenAI error object with the stable taxonomy.

Playground

Checking session…

POST /api/v1/responsesmodelstream

Request as curl

curl https://api.hyperinfer.ai/api/v1/responses \
  -H "Authorization: Bearer $HYPERINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek/deepseek-v4-flash",
  "input": "In one sentence: what is speculative decoding?",
  "instructions": "You are a concise assistant.",
  "max_output_tokens": 256
}'