Skip to content
Docs
Open app

API overview

Call models from your code with the OpenAI and Anthropic formats you already use.

Deference serves models through the formats your SDKs already speak. Change the base URL and the key, and keep the rest of your code. To set up a coding tool instead, see Coding tools.

  • OpenAI formatMost SDKs and toolshttps://deference.si/v1
  • Anthropic formatClaude Code and the Anthropic SDKhttps://deference.si
Anthropic clients add /v1/messages themselves, so their base URL has no /v1. A doubled or missing /v1 returns 404.

Send your key as Authorization: Bearer sk-df-... or as x-api-key: sk-df-.... See Authentication.

Which endpoint

EndpointFormatUse it for
POST /v1/chat/completionsOpenAI Chat CompletionsMost SDKs and tools. Text, vision, tools, structured outputs, streaming
POST /v1/completionsOpenAI legacy CompletionsText completions on models that support them
POST /v1/messagesAnthropic MessagesClaude Code and the Anthropic SDK
POST /v1/responsesOpenAI ResponsesCodex and the OpenAI Responses API
POST /v1/embeddingsOpenAI EmbeddingsSearch and retrieval
POST /v1/imagesOpenRouter ImagesImage generation
GET /v1/modelsOpenAI list, extendedModel ids, prices and limits. No key needed
GET /v1/keyDeferenceThe calling key's limit, spend and available credit

Every response

  • x-request-id is on every response from the six POST endpoints, errors included. A request appears in Activity under that id once its hold opens, including one the provider never answers. Requests refused before that, and GET requests, are not logged.
  • x-deference-cost is the cost in micro-dollars on a successful non-streamed response. It is provisional when the body carries a generation id. On Images, which never have one, a reported cost is final. A success that reports no cost stays unresolved, and the header is 0.
  • Errors use the OpenAI envelope on every endpoint except Messages, which uses Anthropic's. See Errors.

What Deference changes

  • Fields pass through to the provider, which ignores parameters a model does not support. models, fallbacks, route and provider return 400 unsupported_parameter, as does a plugins entry that is not response-healing, a file-parser on cloudflare-ai or native, or context-compression with enabled: false.
  • On Chat Completions and legacy Completions that omit the output cap and use no server tools, Deference can lower the cap it would have sent so the hold fits available credit. A cap you set is kept. Messages and Responses keep their output limits and refuse a request whose hold does not fit.
  • On Chat Completions, legacy Completions, Embeddings and Images, user is replaced with a stable account tag. A model id that is not the catalog id, including a trailing [1m], is replaced with the catalog id on every endpoint. Messages also caps a web-search tool's max_uses. Otherwise Messages and Responses keep the body.
  • Prompts and responses are not stored.

Limits

300 requests per minute and 8 in flight per key. Until an account first adds credit, it is limited to 20 requests per minute across its keys. See Rate limits.

Also in this reference