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
thinkingblock with an emptysignature(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-Afterheader; back off on your side. A provider's own rate-limit headers pass through. - A query string such as
?beta=trueis kept on the way to Claude and dropped on a translated call.