IN ENGLISH · API DOCS

Native Anthropic route: the Messages API, prompt caching and Claude Code

POST https://1xai.ir/anthropic/v1/messages forwards the request body as it is to Anthropic's own Messages API. What the OpenAI compatibility layer lacks works here: prompt caching with cache_control, extended thinking and citations. The official Anthropic SDK and Claude Code connect by changing the base URL and setting a 1xai-* key.

Last updated:

[01]ANTHROPIC (NATIVE)

Messages: POST /anthropic/v1/messages

POST /anthropic/v1/messagescurl
curl https://1xai.ir/anthropic/v1/messages \
  -H "x-api-key: 1xai-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
The official Anthropic SDKpython
from anthropic import Anthropic

client = Anthropic(
    base_url="https://1xai.ir/anthropic",
    api_key="1xai-...",
)

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content[0].text)
  • max_tokens is required; without it the answer is 400 with code invalid_request.
  • The key goes in x-api-key or Authorization: Bearer. The headers anthropic-version and anthropic-beta reach Anthropic; when you send no version, 2023-06-01 is sent.
  • The same route is also at POST /v1/messages, so an SDK whose base URL is the site root works too.
  • The response, usage included, is Anthropic's own. claude-* models only; another vendor's model answers 400, and the message says to call it on /v1.
  • When Anthropic answers 429, 503 or 529, the gateway tries up to 3 times before returning the answer.
[02]ANTHROPIC (NATIVE)

Prompt caching

`cache_control` on a `system` blockcurl
curl https://1xai.ir/anthropic/v1/messages \
  -H "x-api-key: 1xai-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [{
      "type": "text",
      "text": "A long guide repeated in every call…",
      "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{"role": "user", "content": "Summarise this guide."}]
  }'
  • usage.cache_read_input_tokens is what was read from the cache, and it is billed at the model's cheaper cached rate.
  • usage.cache_creation_input_tokens is what was written to the cache, at the cache-write rate; the one-hour cache has its own rate.
  • These rates follow the ratios Anthropic publishes, plus the model's markup (billing).
  • There is no cache_control field on /v1/chat/completions; use this route for Claude prompt caching.
[03]ANTHROPIC (NATIVE)

Extended thinking and tools

  • The thinking field and its budget are sent as they are. When the balance cannot fund more output than the thinking budget, the answer is 402.
  • Your own tools (tools with an input_schema) and tool_choice pass through.
  • The server tools web_search and web_fetch are allowed; search is billed per search. code_execution is refused (hosted tools).
  • Streaming with "stream": true gives Anthropic's own events.
[04]ANTHROPIC (NATIVE)

Token counting and the model list

  • POST /anthropic/v1/messages/count_tokens counts a request's tokens before you send it, and is free.
  • GET /anthropic/v1/models returns the Claude models in Anthropic's shape, and is free.
[05]ANTHROPIC (NATIVE)

Message Batches

With Message Batches you send many Messages requests at once, and Anthropic runs them in the background. The routes are Anthropic's own, under /anthropic:

Message Batches routes
RouteWhat it does
POST /anthropic/v1/messages/batchesWhat it does:Submits a batch; the answer has its id (msgbatch_…)
GET /anthropic/v1/messages/batches/{id}What it does:The batch's status; poll this
GET /anthropic/v1/messages/batches/{id}/resultsWhat it does:The results, one JSON line per request (JSONL)
POST /anthropic/v1/messages/batches/{id}/cancelWhat it does:Cancels the batch
DELETE /anthropic/v1/messages/batches/{id}What it does:Deletes the batch
POST /anthropic/v1/messages/batchescurl
curl https://1xai.ir/anthropic/v1/messages/batches \
  -H "x-api-key: 1xai-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"custom_id": "q-1", "params": {"model": "claude-sonnet-5", "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello"}]}}
    ]
  }'

# the status, with the id of the answer above
curl https://1xai.ir/anthropic/v1/messages/batches/msgbatch_... \
  -H "x-api-key: 1xai-..." -H "anthropic-version: 2023-06-01"

# the results, once processing_status is ended
curl https://1xai.ir/anthropic/v1/messages/batches/msgbatch_.../results \
  -H "x-api-key: 1xai-..." -H "anthropic-version: 2023-06-01"
  • A batch is reachable only with keys of the account that created it; a batch created with a company workspace key, only with keys of that workspace. Any other key gets the answer an unknown id gets: 404 with code not_found.
  • The list of batches (GET /anthropic/v1/messages/batches) is not served through 1xAi: it answers 404 with code path_not_found. Keep the id the submit returns, and read the status and results by it.
  • The batch object's results_url is the batch's results on 1xAi: /anthropic/v1/messages/batches/{id}/results on the host you sent the request to; it is null until the results are ready. So in the Anthropic SDK, messages.batches.results() works with your 1xAi key, and a plain GET of the same path returns the same results.
  • Submitting a batch needs a positive balance; otherwise the answer is 402 with code insufficient_balance. Nothing is held or charged at submit.
  • It is billed once: when the batch's results are first downloaded. Each succeeded request's tokens are billed at 50% of the model's per-token list price (Anthropic's batch rate), plus the model's markup. An errored, expired or cancelled request costs nothing, and later downloads of the same results are free. The charge appears in the usage report as one row per model of the batch (billing).
  • A path is read the same with or without a trailing /, and // counts as one /.
  • A batch submitted before owners were recorded has no owner on record and answers 404; after checking, support can attach it to the key that created it.
  • A key with a model list may POST only the submit and the cancel under /anthropic/v1/messages/batches, and the model of every request in a batch must be on its list; if one is not, the whole batch is refused with 403 and code key_model_not_allowed.
[06]ANTHROPIC (NATIVE)

Claude Code

Claude Codebash
export ANTHROPIC_BASE_URL="https://1xai.ir/anthropic"
export ANTHROPIC_AUTH_TOKEN="1xai-..."
claude

Two environment variables are enough, and no Anthropic account is needed. The step-by-step guide: connecting Claude Code.

1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.