Chat Completions


POST /api/v1/chat/completions

OpenAI Chat Completions format. Works with every model in the catalog — including Anthropic-slugged models — via any-to-any translation.

Request body

Body — application/json (required)

modelstringrequired

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

messagesobject[]required

Conversation messages; at least one is required.

Show 6 nested fields

rolestringrequired

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

Possible values: system developer user assistant tool

contentstring | (text | image_url | file)[] | null

Message content: a string, an array of content parts, or null.

Show 2 variants

stringstring

(text | image_url | file)[](text | image_url | file)[]

Show 3 variants

textobject

Show 2 nested fields

type"text"required

textstringrequired

The text content.

image_urlobject

Show 2 nested fields

type"image_url"required

image_urlobjectrequired

Show 2 nested fields

urlstringrequired

Image URL or data: URL.

detailstring

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

fileobject

Show 2 nested fields

type"file"required

fileobjectrequired

Show 4 nested fields

filenamestring

Optional filename hint.

file_datastring

File contents as a data: URL.

file_urlstring

File contents as a fetchable URL.

file_idstring

Uploaded file id (not supported — use file_data or file_url).

namestring

Optional participant name.

reasoningstring | null

Prior reasoning text (OpenRouter extension).

tool_callsobject[]

Tool calls produced by the model.

Show 3 nested fields

idstringrequired

Tool call id assigned by the model.

type"function"required

functionobjectrequired

Show 2 nested fields

namestringrequired

Function name.

argumentsstringrequired

JSON-encoded arguments string.

tool_call_idstring

Tool call id this result message answers.

tools(function | object)[]

Function tools and/or OpenRouter server-tool activations (024-R26).

Show 2 variants

functionobject

Show 2 nested fields

type"function"required

functionobjectrequired

Show 4 nested fields

namestringrequired

Function name.

descriptionstring

Natural-language description for the model.

parametersobject

JSON Schema for the function arguments.

strictboolean

Enable OpenAI strict structured outputs.

objectobject

Show 4 nested fields

typestringrequired

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

parametersobject

OpenRouter server-tool parameters.

max_usesinteger

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

eventsboolean

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

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

functionobjectrequired

Show 1 nested field

namestringrequired

Function name to force.

parallel_tool_callsboolean

Allow the model to call tools in parallel.

max_tokensinteger

Max output tokens (legacy name; prefer max_completion_tokens).

max_completion_tokensinteger

Max output tokens.

temperaturenumber

Sampling temperature, 0–2.

top_pnumber

Nucleus sampling probability, 0–1.

stopstring | string[]

Stop sequence(s); generation halts when hit.

response_formatobject

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

Show 2 nested fields

typestringrequired

Response format mode.

Possible values: text json_object json_schema

json_schemaobject

The JSON Schema when type is json_schema.

Show 3 nested fields

namestringrequired

Schema name.

schemaobjectrequired

JSON Schema describing the response.

strictboolean

Enable strict structured outputs.

reasoning_effortstring

Possible values: none minimal low medium high xhigh max

streamboolean

Stream SSE chunks instead of returning one object.

stream_optionsobject

Streaming options. Usage is always emitted (002-R8).

Show 1 nested field

include_usageboolean

Emit a final usage chunk.

pluginsobject[]

Server-tool activations (OpenRouter plugins idiom, 002-R11).

Show 3 nested fields

idstringrequired

Server tool id (OpenRouter plugins idiom, 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.

web_search_optionsobject

OpenAI web_search_options → our `web_search` server tool (024-R26).

Show 2 nested fields

search_context_sizestring

How much context to retrieve.

Possible values: low medium high

user_locationobject

Approximate user location for location-biased results.

Show 2 nested fields

type"approximate"

approximateobject

Show 4 nested fields

citystring

regionstring

countrystring

timezonestring

hi_tool_eventsboolean

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

userstring

End-user identifier for abuse monitoring.

service_tierstring

OpenAI service tier — accepted but the gateway owns tiering.

ninteger

Number of choices. Only n=1 is supported (024-R3/D6).

seedinteger

Sampling seed for best-effort determinism.

frequency_penaltynumber

Penalize tokens by frequency, -2 to 2.

presence_penaltynumber

Penalize tokens by presence, -2 to 2.

logit_biasmap<string, number>

Token-id → bias map (-100 to 100).

logprobsboolean

Return log probabilities of output tokens.

top_logprobsinteger

Top-N log probabilities per token (requires logprobs:true).

min_pnumber

Min-p sampling threshold, 0–1.

top_anumber

Top-a sampling threshold, 0–1.

repetition_penaltynumber

Repetition penalty, 0–2.

verbositystring

Output verbosity dial.

Possible values: low medium high xhigh max

predictionobject

Predicted Outputs content hint.

Show 2 nested fields

type"content"required

contentstring | any[]required

Predicted content.

modalitiesstring[]

Requested output modalities. Only text is supported.

audioany

Audio output options — not supported (text-only deployment).

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

max_tokens and max_completion_tokens are aliases — either caps generated tokens at the model’s max output. stream: true switches to SSE — see Streaming; stream_options is accepted for compatibility (the final usage chunk is always emitted). plugins is the HyperInfer extension for server tools.

Beyond the fields above, the full OpenAI sampling / tool / output surface is accepted and forwarded — seed, frequency_penalty, presence_penalty, logit_bias, logprobs, parallel_tool_calls, per-tool strict, verbosity, prediction, and so on — along with OpenRouter extensions (min_p, top_a, repetition_penalty, provider routing, transforms) and any custom top-level field, all passed through verbatim to the OpenAI-compatible upstream. A few parameters are rejected rather than silently ignored (service_tier, n > 1, audio / non-text modalities) — see Errors.

Response


{
  "id": "gen-abc123",
  "object": "chat.completion",
  "created": 1767312000,
  "model": "anthropic/claude-sonnet-4.5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello there, all five words." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 7,
    "total_tokens": 19,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

The id is gen-<request id> — pass the request ID (also returned in the X-Request-Id header) to GET /generation for cost and latency metadata.

Response schema

200Response

The completion. With `stream: true`, an SSE stream instead (see the text/event-stream variant).

application/json

idstringrequired

gen-<request id> — pass the request id to GET /api/v1/generation.

object"chat.completion"required

createdintegerrequired

Unix seconds.

modelstringrequired

choicesobject[]required

Show 4 nested fields

indexinteger

messageobject

Show 4 nested fields

role"assistant"

contentstring | null

reasoningstring

tool_callsobject[]

Show 3 nested fields

idstring

type"function"

functionobject

Show 2 nested fields

namestring

argumentsstring

finish_reasonstring

Possible values: stop length tool_calls content_filter

logprobsnull

usageobjectrequired

Show 6 nested fields

prompt_tokensintegerrequired

completion_tokensintegerrequired

total_tokensintegerrequired

prompt_tokens_detailsobject

Show 2 nested fields

cached_tokensinteger

audio_tokensinteger

Audio input tokens; omitted when 0.

completion_tokens_detailsobject

Show 4 nested fields

reasoning_tokensinteger

audio_tokensinteger

Audio output tokens; omitted when 0.

accepted_prediction_tokensinteger

Predicted Outputs accepted tokens; omitted when 0.

rejected_prediction_tokensinteger

Predicted Outputs rejected tokens; omitted when 0.

costnumber

HyperInfer usage-accounting extension: total cost in credits (USD).

text/event-streamSSE stream

SSE stream of `chat.completion.chunk` objects (`data:` frames): a role frame, then content/reasoning/tool_call deltas, a finish_reason frame, a final usage-only chunk (always emitted — stream_options.include_usage semantics, 002-R8), and `data: [DONE]`. 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/chat/completions \
  -H "Authorization: Bearer $HYPERINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "In one sentence: what is speculative decoding?" }
    ],
    "max_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 completion = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.5",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "In one sentence: what is speculative decoding?" },
  ],
  max_tokens: 256,
});

Python


import os
from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.hyperinfer.ai/api/v1",
    api_key=os.environ["HYPERINFER_API_KEY"],
)
 
completion = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "In one sentence: what is speculative decoding?"},
    ],
    max_tokens=256,
)

Errors

OpenAI error object with the stable taxonomy, e.g. HTTP 402:


{ "error": { "message": "…", "type": "insufficient_credits", "code": "insufficient_credits", "param": null } }

Playground

Checking session…

POST /api/v1/chat/completionsmodelstream

Request as curl

curl https://api.hyperinfer.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $HYPERINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek/deepseek-v4-flash",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise assistant."
    },
    {
      "role": "user",
      "content": "In one sentence: what is speculative decoding?"
    }
  ],
  "max_tokens": 256,
  "temperature": 0.7
}'