Messages


POST /api/v1/messages

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

Authenticate with either Authorization: Bearer $KEY (like every HyperInfer endpoint) or the Anthropic-native x-api-key: $KEY header — so Anthropic SDKs and tools that set ANTHROPIC_API_KEY (e.g. Claude Code) work unchanged. No anthropic-version header is required.

Request body

Body — application/json (required)

modelstringrequired

Model slug to invoke (e.g. anthropic/claude-opus-4.1).

max_tokensintegerrequired

Max output tokens (required by Anthropic).

messagesobject[]required

Conversation turns; at least one is required. System is top-level, not here.

Show 2 nested fields

rolestringrequired

Conversation role. A system turn here is hoisted into the system prompt.

Possible values: system user assistant

Message content: a string or an array of content blocks.

Show 2 variants

stringstring

Show 6 variants

textobject

Show 3 nested fields

type"text"required

textstringrequired

The text content.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

thinkingobject

Show 3 nested fields

type"thinking"required

thinkingstringrequired

Prior thinking text.

signaturestring

Thinking signature for multi-turn continuity.

imageobject

Show 3 nested fields

type"image"required

sourcebase64 | urlrequired

Image source (base64 or URL).

Show 2 variants

base64object

Show 3 nested fields

type"base64"required

media_typestringrequired

MIME type of the base64 content.

datastringrequired

Base64-encoded content.

urlobject

Show 2 nested fields

type"url"required

urlstringrequired

Fetchable URL of the content.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

documentobject

Show 4 nested fields

type"document"required

sourcebase64 | urlrequired

Document source (base64 or URL).

Show 2 variants

base64object

Show 3 nested fields

type"base64"required

media_typestringrequired

MIME type of the base64 content.

datastringrequired

Base64-encoded content.

urlobject

Show 2 nested fields

type"url"required

urlstringrequired

Fetchable URL of the content.

titlestring

Optional document title.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

tool_useobject

Show 5 nested fields

type"tool_use"required

idstringrequired

Tool call id.

namestringrequired

Tool name.

inputobjectrequired

JSON object of tool arguments.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

tool_resultobject

Show 5 nested fields

type"tool_result"required

tool_use_idstringrequired

Tool call id this result answers.

contentstring | (text | image)[]

Tool result content (string or text/image blocks).

Show 2 variants

stringstring

(text | image)[](text | image)[]

Show 2 variants

textobject

Show 3 nested fields

type"text"required

textstringrequired

The text content.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

imageobject

Show 3 nested fields

type"image"required

sourcebase64 | urlrequired

Image source (base64 or URL).

Show 2 variants

base64object

Show 3 nested fields

type"base64"required

media_typestringrequired

MIME type of the base64 content.

datastringrequired

Base64-encoded content.

urlobject

Show 2 nested fields

type"url"required

urlstringrequired

Fetchable URL of the content.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

is_errorboolean

Mark this result as an error.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

systemstring | object[]

System prompt: a string or an array of text blocks (with cache_control).

Show 2 variants

stringstring

object[]object[]

Show 3 nested fields

type"text"required

textstringrequired

The text content.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

toolsobject[]

Tools the model may call.

Show 4 nested fields

namestringrequired

Tool name.

descriptionstring

Natural-language description for the model.

input_schemaobjectrequired

JSON Schema for the tool arguments.

cache_controlobject

Prompt-cache breakpoint (0054-R1).

Show 1 nested field

type"ephemeral"required

tool_choiceobject

How to choose tools.

Show 3 nested fields

typestringrequired

auto=model decides, any=required, tool=force a specific tool, none=disabled.

Possible values: auto any tool none

namestring

Tool name to force (required when type is tool).

disable_parallel_tool_useboolean

Disable parallel tool calls (inverts to parallel_tool_calls).

temperaturenumber

Sampling temperature, 0–1.

top_pnumber

Nucleus sampling probability, 0–1.

stop_sequencesstring[]

Stop sequences; generation halts when hit.

streamboolean

Stream SSE events instead of returning one object.

thinkingobject

Extended thinking controls.

Show 3 nested fields

typestringrequired

Thinking mode: enabled (with budget), disabled, or adaptive (model decides).

Possible values: enabled disabled adaptive

budget_tokensinteger

Thinking budget in tokens (requires type enabled).

displaystring

Thinking display mode — accepted and ignored.

Possible values: summarized omitted

output_configobject

Output configuration (top-level effort dial).

Show 1 nested field

effortstring

Soft reasoning-effort dial (default high).

Possible values: low medium high xhigh max

top_kinteger

Top-k sampling.

metadataobject

Arbitrary request metadata.

pluginsobject[]

Server-tool activations (HyperInfer extension, 002-R11).

Show 3 nested fields

idstringrequired

Server tool id (HyperInfer extension, mirrors chat completions plugins).

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.

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.

max_tokens is required by this format. system is the top-level system prompt (not a message). stream: true switches to the Anthropic event stream — see Streaming. plugins is the HyperInfer extension for server tools.

JSON mode is not expressible in this format — use a tool definition to enforce structured output (capability gaps).

Response


{
  "id": "msg_ghi789",
  "type": "message",
  "role": "assistant",
  "model": "openai/gpt-4o-mini",
  "content": [
    { "type": "text", "text": "Speculative decoding drafts tokens with a small model…" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 31
  }
}

Reasoning models emit thinking content blocks ahead of the text. The id is msg_<request id> — pass the request ID (also returned in the X-Request-Id header) to GET /generation.

Response schema

200Response

The message. With `stream: true`, an SSE stream instead.

application/json

idstringrequired

msg_<request id>.

type"message"required

role"assistant"required

modelstringrequired

contentobject[]required

Content blocks: `text`, `thinking`, and `tool_use`.

stop_reasonstringrequired

Possible values: end_turn max_tokens tool_use refusal pause_turn model_context_window_exceeded

stop_sequencestring | null

usageobjectrequired

Anthropic semantics: input_tokens excludes cache reads.

Show 4 nested fields

input_tokensinteger

output_tokensinteger

cache_read_input_tokensinteger

cache_creation_input_tokensinteger

text/event-streamSSE stream

Anthropic content-block SSE protocol (`event:` + `data:` frames): `message_start`, then `content_block_start` / `content_block_delta` / `content_block_stop` per block (text_delta, thinking_delta, input_json_delta), `message_delta` with stop_reason + usage (002-R8), and `message_stop`. 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.

type"error"required

errorobjectrequired

Show 4 nested fields

typestringrequired

Anthropic-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

messagestringrequired

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.

request_idstring

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/messages \
  -H "Authorization: Bearer $HYPERINFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "max_tokens": 256,
    "system": "You are a concise assistant.",
    "messages": [
      { "role": "user", "content": "In one sentence: what is speculative decoding?" }
    ]
  }'

TypeScript


import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({
  baseURL: "https://api.hyperinfer.ai/api", // SDK appends /v1/messages
  authToken: process.env.HYPERINFER_API_KEY,
});
 
const message = await client.messages.create({
  model: "openai/gpt-4o-mini",
  max_tokens: 256,
  system: "You are a concise assistant.",
  messages: [{ role: "user", content: "In one sentence: what is speculative decoding?" }],
});

Python


import os
from anthropic import Anthropic
 
client = Anthropic(
    base_url="https://api.hyperinfer.ai/api",  # SDK appends /v1/messages
    auth_token=os.environ["HYPERINFER_API_KEY"],
)
 
message = client.messages.create(
    model="openai/gpt-4o-mini",
    max_tokens=256,
    system="You are a concise assistant.",
    messages=[{"role": "user", "content": "In one sentence: what is speculative decoding?"}],
)

Errors

Anthropic error envelope with the stable taxonomy, e.g. HTTP 402:


{ "type": "error", "error": { "type": "insufficient_credits", "message": "…" } }

Playground

Checking session…

POST /api/v1/messagesmodelstream

Request as curl

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