Anthropic compatibility

POST /v1/messages speaks the Anthropic Messages API. Claude Code and the Anthropic SDKs add /v1/messages themselves, so their base URL has no /v1.

import anthropic

client = anthropic.Anthropic(
    base_url="https://deference.si",
    api_key="sk-df-...",
)

message = client.messages.create(
    model="anthropic/claude-sonnet-5.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(message.content[0].text)

What passes through

• anthropic-version and anthropic-beta headers pass through as sent. The body keeps its Anthropic format, including thinking and tool-use blocks.
• Streams are relayed as they arrive, including ping events. Nothing is buffered.
• system and cache_control blocks keep their position, so prompt caching works.
• A query string such as ?beta=true is ignored.
• Provider errors that describe your request keep their status: 400, 403, 404, 408, 409, 413, 422 and 429. Deference rebuilds their bodies in the Anthropic envelope, keeping a valid Anthropic error's type and wording and removing provider metadata. Other bodies use Deference's type and a replacement message. A provider 401 or 402 becomes 503 with overloaded_error, and any other provider failure becomes 502 with api_error. retry-after is a whole number of seconds; an HTTP-date is dropped.
• anthropic-ratelimit-* and x-should-retry response headers are passed on when the provider sends them.

Set max_tokens to an output limit your available credit can cover. Deference never lowers it on Messages. A provider-run web_search tool's max_uses cannot exceed the request's allowed tool steps, at most 30. If omitted, it uses that allowance. See Messages.

Credentials

Send the key as x-api-key: sk-df-... or as Authorization: Bearer sk-df-.... The Anthropic SDK sends the first. Claude Code sends the second when you set ANTHROPIC_AUTH_TOKEN.

Model ids

Use the catalog id, for instance anthropic/claude-sonnet-5.5. A trailing [1m] is accepted: Deference strips it, looks the model up without it, and sends the catalog id. The provider does not see [1m]. Other providers' models are accepted too, but thinking blocks and tool use follow each model's own behavior.

Errors

Errors use Anthropic's envelope: type: "error", an error object with type and message, and Deference's request_id. The x-request-id and request-id headers carry the same id. Generated 409 errors use conflict_error, and gateway 504 errors use timeout_error. See Errors.

Not available

POST /v1/messages/count_tokens is not available. Claude Code falls back to an estimate when it cannot count tokens.