Skip to content

Messages API

POST /v1/messages is the endpoint the Anthropic SDKs, Claude Code and most Anthropic-format tools call. Through the gateway it reaches every provider your organisation has set up: Claude as sent, and OpenAI, Gemini and the rest translated both ways, so your code reads an Anthropic answer whichever model wrote it.

What it is

Anthropic's Messages API: a list of messages, an optional system, max_tokens, and optionally tools, thinking and stream. The gateway accepts it at https://<your-gateway>/v1/messages.

Model behind the name What the gateway does
Claude on Anthropic Sends the call as it is
Claude on Amazon Bedrock Sends it as it is (Bedrock's Claude speaks this format); a stream comes back as Anthropic events
Claude on Vertex AI Sends it as it is
OpenAI, Azure OpenAI Translates the call to Chat Completions, and the answer back
Gemini, Vertex AI (Gemini) Translates the call to generateContent, and the answer back
Bedrock's other models (Nova, Llama, Mistral, Cohere) Translates it; images and documents are not carried to these

You don't choose the route: the model name does. An admin decides in the Control room which provider serves each name.

The two settings

Setting Environment variable Python TypeScript Value
Base address ANTHROPIC_BASE_URL base_url baseURL https://<your-gateway>
Key ANTHROPIC_API_KEY api_key apiKey Your Vidai key (starts vk_)
export ANTHROPIC_BASE_URL="https://<your-gateway>"
export ANTHROPIC_API_KEY="vk_…"

Details per SDK: Anthropic SDK for Python, Anthropic SDK for TypeScript.

A minimal call

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=200,
    messages=[{"role": "user", "content": "Say hello in Dutch."}],
)
print(message.content[0].text)
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY

const message = await client.messages.create({
  model: "claude-sonnet-4.5",
  max_tokens: 200,
  messages: [{ role: "user", content: "Say hello in Dutch." }],
});
console.log(message.content[0].type === "text" ? message.content[0].text : message.content[0]);
curl https://<your-gateway>/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4.5","max_tokens":200,
       "messages":[{"role":"user","content":"Say hello in Dutch."}]}'

Put gpt-4.1 or gemini-3.5-flash (for example) in model and the same code gets an Anthropic Message back: content blocks, a stop_reason and a usage block, translated from the other provider's answer.

Streaming

with client.messages.stream(
    model="gemini-3.5-flash",
    max_tokens=200,
    messages=[{"role": "user", "content": "Count to five."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="")
    final = stream.get_final_message()
print(final.usage)
const stream = client.messages.stream({
  model: "gemini-3.5-flash",
  max_tokens: 200,
  messages: [{ role: "user", content: "Count to five." }],
});
stream.on("text", (text) => process.stdout.write(text));
const final = await stream.finalMessage();
console.log(final.usage);
curl -N https://<your-gateway>/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"gemini-3.5-flash","max_tokens":200,"stream":true,
       "messages":[{"role":"user","content":"Count to five."}]}'

A stream from any provider arrives as Anthropic's own events: message_start, content_block_start, content_block_delta (text_delta, input_json_delta), content_block_stop, message_delta (with stop_reason and usage) and message_stop. Translation adds about a millisecond; the rest is the model.

If something fails after the first event has reached you, the gateway closes the connection rather than sending an error event, and the call is recorded as cut short. A fallback model is only tried before the first byte.

Tool calls

tools and tool_choice work as Anthropic documents them, on every provider: tool calls come back as tool_use blocks with stop_reason: "tool_use", and you send results as tool_result blocks.

tools = [{
    "name": "get_weather",
    "description": "Weather for a city",
    "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}]
message = client.messages.create(
    model="gpt-4.1",
    max_tokens=300,
    tools=tools,
    messages=[{"role": "user", "content": "Weather in Utrecht?"}],
)
print([b for b in message.content if b.type == "tool_use"])
const message = await client.messages.create({
  model: "gpt-4.1",
  max_tokens: 300,
  tools: [{
    name: "get_weather",
    description: "Weather for a city",
    input_schema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
  }],
  messages: [{ role: "user", content: "Weather in Utrecht?" }],
});
console.log(message.content.filter((b) => b.type === "tool_use"));

On another provider's model:

You send What happens
Your own tools (input_schema) Carried both ways; a tool name the other provider can't take is renamed on the way and restored in the answer
strict: true on a tool Kept where the schema meets the provider's strict rules; otherwise dropped and reported as strict
web_search_20250305 Becomes Google Search on Gemini, or web search on OpenAI models that have it; otherwise dropped and reported as web_search. Gemini can't mix search with your own tools, so your tools win
computer_20241022 Dropped and reported as server_tool
bash_20250124, text_editor_20250124 Refused with a 400: nothing equivalent exists elsewhere

Reading what the gateway did

raw = client.messages.with_raw_response.create(
    model="gemini-3.5-flash",
    max_tokens=50,
    messages=[{"role": "user", "content": "Hi"}],
)
print(raw.headers.get("x-vidai-request-id"))  # quote this; paste it into Request logs › Request reference
print(raw.headers.get("x-vidai-model"))       # the model that answered
print(raw.headers.get("x-vidai-adapted"))     # what translation changed or couldn't carry
message = raw.parse()
const { data: message, response } = await client.messages
  .create({ model: "gemini-3.5-flash", max_tokens: 50, messages: [{ role: "user", content: "Hi" }] })
  .withResponse();
console.log(response.headers.get("x-vidai-request-id"));
console.log(response.headers.get("x-vidai-model"));
console.log(response.headers.get("x-vidai-adapted"));

x-vidai-adapted lists, by the names you sent, what had no equivalent on the provider that answered and was dropped, clamped or approximated: never a failed call. Tokens you may meet on this endpoint:

Token Meaning
thinking Extended thinking was dropped (the model can't reason) or its budget clamped
cache_control Cache markers removed (the provider caches on its own terms)
top_k, metadata, … A field with no equivalent there, by its own name
stop_sequences More than 4 stop sequences: the first 4 went to the provider and the gateway enforced the rest
strict, web_search, server_tool See Tool calls
tool_result.is_error, tool_result.content Part of a tool result the other format can't carry
x-vidai-translation You asked for a translation profile this key may not choose; the call went ahead with the key's own

Translation profile. Each key has a Translation between API formats setting: Standard, or Keep what the other format can't say (carries near equivalents such as the service tier). If the key has Let apps choose the translation per call, send x-vidai-translation: default or x-vidai-translation: preserve on one call; x-vidai-translation-profile in the answer says which one applied.

Other headers: x-vidai-requested-model, x-vidai-routing-rule, x-vidai-provider-key, x-vidai-fallback, x-vidai-fallback-from, x-vidai-fallback-attempts and x-vidai-pseudonymised. Cost is never in the answer: find the call in Request logs.

Errors

The gateway's own errors, and a translated provider's errors, come in Anthropic's shape, so the SDK raises its usual exceptions. A Claude provider's own error passes through as Anthropic wrote it.

{"type":"error","error":{"type":"permission_error","message":"…"}}
Status error.type Python exception Common gateway codes (x-vidai-error-code)
400 invalid_request_error BadRequestError bad_request, provider_override_not_allowed, a server tool another provider can't run
401 authentication_error AuthenticationError missing_api_key, invalid_api_key, conflicting_auth_headers
403 permission_error PermissionDeniedError model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
403 authentication_error PermissionDeniedError api_key_disabled
404 not_found_error NotFoundError model_not_found, endpoint_not_found
413 invalid_request_error RequestTooLargeError payload_too_large
429 rate_limit_error RateLimitError rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
502, 504 api_error InternalServerError, DeadlineExceededError upstream_unreachable, upstream_closed, upstream_timeout
503 overloaded_error ServiceUnavailableError fallback_exhausted, ai_traffic_suspended, provider_disabled
try:
    client.messages.create(model="claude-sonnet-4.5", max_tokens=10,
                           messages=[{"role": "user", "content": "Hi"}])
except anthropic.APIStatusError as e:
    print(e.status_code, e.response.headers.get("x-vidai-error-code"))
    print(e.response.headers.get("x-vidai-request-id"))
try {
  await client.messages.create({ model: "claude-sonnet-4.5", max_tokens: 10, messages: [{ role: "user", content: "Hi" }] });
} catch (e) {
  if (e instanceof Anthropic.APIError) {
    console.log(e.status, e.headers?.get("x-vidai-error-code"), e.headers?.get("x-vidai-request-id"));
  }
}

An Anthropic 529 overloaded from Claude reaches a non-Anthropic client as a 503; Anthropic clients see it as sent. A key that's switched off carries a short reason beside api_key_disabled in the error (for example agent_suspended); treat the list of reasons as open-ended.

Model names

Send the names your organisation approved, as listed under Models in the Control room; GET https://<your-gateway>/v1/models lists exactly those your key may call. Any name works on this endpoint, whichever provider serves it. x-vidai-model says which model really answered. See Model names.

What goes through the gateway

Feature Claude (Anthropic, Bedrock, Vertex AI) OpenAI, Azure, Gemini, Vertex AI Gemini
Text, multi-turn, system (also mid-conversation) As sent Translated
Streaming As sent Translated to Anthropic events
Your own tools, tool_choice As sent Translated
Structured output (output_config.format) As sent Translated
Images (base64) As sent Translated
Images by URL As sent (Bedrock: removed and reported as content.image_url) OpenAI: translated; Gemini: may fail, send base64
Extended thinking (thinking) As sent Mapped to reasoning effort (OpenAI) or thinkingConfig (Gemini); dropped and reported on a model that can't reason
Prompt caching (cache_control) As sent Markers removed; the provider's own cache hits still show in usage.cache_read_input_tokens
anthropic-beta features As sent The header isn't sent on; mapped tools handled as above

Check it works in a minute

curl -s https://<your-gateway>/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4.5","max_tokens":5,"messages":[{"role":"user","content":"ping"}]}' -i | grep -i -e "^HTTP" -e "x-vidai-model"

A 200 and an x-vidai-model line mean the address and key are right. The call shows in Request logs within seconds.

Good to know

  • On another provider's model, a reasoning summary comes back as a thinking block with an empty signature (only Claude can sign). When that history goes back to Claude, the unsigned blocks are removed and reported, so switching models mid-conversation works; a switch in the middle of a tool-use loop with thinking on may not.
  • The SDK retries twice by default (on 408, 409, 429 and 5xx). A fallback chain may already have tried another model before you see an error; set max_retries=0 (maxRetries: 0) if you don't want both.
  • The gateway's own 429 has no Retry-After header; back off on your side. A provider's own rate-limit headers pass through.
  • A query string such as ?beta=true is kept on the way to Claude and dropped on a translated call.