# KeyDealer API

KeyDealer provides an OpenAI-compatible API at https://api.keydealer.ru/v1.
Public model names identify the model requested by the customer. Private routing and internal infrastructure are not part of the public API contract.

## Endpoints

- Service contract and current limits: GET https://api.keydealer.ru/v1
- Available models, base catalog rates and capabilities: GET https://api.keydealer.ru/v1/models
- Exact balance and account-effective rates: GET https://api.keydealer.ru/v1/balance (Bearer API key required)
- Chat completions: POST https://api.keydealer.ru/v1/chat/completions
- Image generation: POST https://api.keydealer.ru/v1/images/generations

## Request contract and model capabilities

- Unknown top-level fields are rejected with HTTP 400 and error.code=unsupported_parameter. They are never accepted silently.
- Supported top-level fields are defined in https://keydealer.ru/openapi.yaml.
- Each model exposes capabilities with one of three statuses: verified, unsupported, or unknown.
- verified means the behavior was confirmed by a controlled probe; unsupported means it is known not to work; unknown means KeyDealer makes no claim yet.
- Requests for unsupported capabilities fail before model execution and before billing.
- Requests for unknown capabilities may be attempted. The response includes x-kd-unverified-capabilities so clients can detect this case.
- The capability matrix covers chat completions, streaming, tools, forced tool choice, parallel tool calls, tool-result messages, streaming with tools, JSON output, and a verified maximum output size when known.
- GPT Image 2 and GPT Image 1.5 support text-to-image generation through POST /v1/images/generations.
- Supported image sizes: 1024x1024, 1024x1536 and 1536x1024. Supported qualities: low, medium and high. One request creates one image (n=1).
- Image editing is not part of the current public API contract. Check capabilities.image_edits in GET /v1/models before relying on it.

## Billing contract

- Balance and all rates are denominated in Russian rubles.
- GET /v1/models returns base catalog rates with pricing.scope=base_catalog.
- GET /v1/balance returns account-effective rates with pricing_scope=account_effective. This is the pre-request source of truth for individual terms.
- GET /v1/balance is never cached. It returns the exact ruble balance and separately calculated input/output token equivalents for every currently available model.
- Exact charge = prompt_tokens * input rate / 1,000,000 + completion_tokens * output rate / 1,000,000.
- Image generation uses a fixed RUB price per successful image. The exact base price by model, size and quality is published by GET /v1/models; account-effective prices and the number of images affordable from the current balance are returned by GET /v1/balance.
- A failed image request is not charged. A successful response includes keydealer_billing.charged_microrubles and operation_id.
- The JSON response repeats the effective rates and exact amount in keydealer_billing. keydealer_billing.charged_microrubles is the post-request source of truth.
- prompt_tokens may include system context required by the selected route. GET /v1/models publishes an estimate plus p50, p95 and sample size when measured.
- Route context can vary by request. usage in the completed response, not the estimate, is authoritative for charging.
- Prompt cache is not promised unless GET /v1/models explicitly returns prompt_cache.status=verified. A client-supplied cache_control field alone is not evidence of a cache hit or a discount.
- Optional KD Context beta can measure or conservatively compact client-side context before sending. Modes: passthrough, strict (default, no body changes), smart (explicit conservative transforms).
- KD Context does not create model-side KV cache. Public guide: https://keydealer.ru/kd-context.md
- usage.prompt_tokens_details.estimated_user_tokens is an approximate tokenizer-independent estimate of the customer-supplied part. It is informational and is not used as the final charge source.
- usage values returned after model execution are the source of the final charge. KeyDealer does not apply a hidden token multiplier.
- x-request-id and keydealer_billing.operation_id identify the same operation shown in cabinet request history.

## Technical limits and retries

- The current production baseline is published by GET /v1 and may be changed through configuration.
- Default request body limit: 4 MiB.
- Default sanitized response limit: 32 MiB.
- Default model request timeout: 180 seconds.
- Default global rate limit: 120 requests per minute. Read X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After rather than hard-coding these values.
- Retry HTTP 429 and 503 with exponential backoff and jitter. Do not retry 400, 401, 402, 404, or 413 without changing the request or account state.
- Stable error codes include invalid_request, unsupported_parameter, invalid_api_key, insufficient_balance, model_not_found, rate_limit_exceeded, model_service_unavailable, and not_found.

## Data and diagnostics

- API responses expose only KeyDealer-owned request, completion and tool-call identifiers.
- Private URLs, internal route identifiers, procurement coefficients, credentials and raw infrastructure errors are never included in public responses.
- Request content retention is controlled per API key. Token counters and billing records remain available because they are required for charging and support.

## Blog and editorial policy

- Blog index: https://keydealer.ru/blog/
- Articles are authored under a named person, Evgeny Chaplygin, and the publisher is the sole proprietorship listed on https://keydealer.ru/about
- Every numeric claim is sourced from a first-party page: the model developer's own pricing or deprecation documentation, or the Central Bank of Russia for the USD/RUB rate. Source links are listed at the end of each article that contains numbers.
- Ruble figures derived from USD list prices are dated. They are valid for the exchange rate on the stated date and not after.
- If an official figure is not published, the article says so instead of substituting an estimate.
- Model capability claims follow the verified / unsupported / unknown statuses used by GET /v1/models. An unknown capability is never presented as supported.
- Availability claims follow the live GET /v1/models response, not the marketing catalog.
- Current articles:
  - https://keydealer.ru/blog/pobegi-agentov-iz-pesochnicy/ — dated timeline of the incident in which an agent reached external infrastructure, presented at Black Hat USA 2026 on 2026-08-06: write access to a package service discovered on 05-08, SSRF-based indirect internet access on 05-26, zero-day RCE exploited on 06-26, attacks on OpenAI's own infrastructure 07-08 to 07-19, and attribution only on 07-20. The practical conclusion is about tool permissions rather than models: allow-lists over deny-lists, isolated writes, no secrets in context, logged tool calls, and a separate API key with its own limit for agent workloads.
  - https://keydealer.ru/blog/assistants-api-zakryvaetsya/ — OpenAI shuts down the Assistants API on 2026-08-26, recommended replacement is the Responses API together with the Conversations API. Because the Assistants API kept conversation state on the provider side, migration is an architecture change rather than a model-name change. Chat Completions is not affected by this date.
  - https://keydealer.ru/blog/tokenpocalypse-kompanii-rezhut-rashody/ — where enterprise AI spend actually comes from, based on 404 Media reporting on an internal Accenture meeting: non-engineers drove most token usage, and converting PDF pages into images before extraction was a major cost driver. Includes a worked monthly calculation for a 100-person assistant showing a 9.3x spread by rate and a 26.7x spread by final bill once route system context is included.
  - https://keydealer.ru/blog/sluzhebnyy-kontekst-marshruta/ — route system context measured per model and published in GET /v1/models as billing.estimated_route_context_tokens: about 2000 tokens for Gemini and GLM, 2700 for the GPT line and Grok, 7062 for Haiku 4.5, 9500 for the Opus line and Sonnet 5, measured 2026-08-06. On a thousand short requests this overhead alone costs 8 RUB on GLM-4.7 and 617 RUB on Opus 5. The final charge always follows usage in the completed response, not the published estimate.
  - https://keydealer.ru/blog/smena-rukovodstva-deepmind/ — Google DeepMind leadership change of 2026-08-05: Demis Hassabis moved from CEO to chairman of DeepMind and chief scientist at Alphabet, Koray Kavukcuoglu took operational control, Jeff Dean left Google after 27 years to co-found Discovery Loop. Gemini API prices and deprecation dates were unchanged as of 2026-08-08.
  - https://keydealer.ru/blog/anthropic-svoi-chipy/ — Anthropic is in early talks with Samsung about a custom inference accelerator, reported by The Information and TechCrunch on 2026-07-02. No final agreement and no official Anthropic announcement exist; OpenAI is pursuing a comparable custom inference processor with Broadcom. No effect on published Claude pricing.
  - https://keydealer.ru/blog/kalendar-otklyucheniy-modeley-2026/ — model shutdown calendar to the end of 2026, compiled from vendor deprecation pages: OpenAI retires gpt-5.2-chat-latest and gpt-5.3-chat-latest on 2026-08-10 (replacement gpt-5.6-sol), closes the Assistants API on 2026-08-26, retires legacy snapshots including gpt-4o-2024-05-13 on 2026-10-23 and the original gpt-5-2025-08-07 with o3 on 2026-12-11; Anthropic publishes "not sooner than" dates with at least 60 days notice, the nearest being 2026-09-29 for Sonnet 4.5; Google states its dates are earliest-possible and its current text models have none; Z.ai publishes no shutdown schedule at all. Also documents that temperature, top_p and top_k return HTTP 400 on Claude Opus 4.7 and newer.
  - https://keydealer.ru/blog/skolko-stoit-1m-tokenov-v-rublyah/ — official per-million-token prices of OpenAI, Anthropic and Google converted to rubles at the Central Bank rate of 82.1665 RUB per USD on 2026-08-08; explains that Claude 4.7 and newer use a tokenizer producing about 30% more tokens for the same text, that Claude Sonnet 5 introductory pricing ends 2026-08-31, and that Gemini 3.1 Pro doubles its input rate above 200k tokens.

Human-readable documentation: https://keydealer.ru/docs
OpenAPI contract: https://keydealer.ru/openapi.yaml
Terms: https://keydealer.ru/legal/terms
Privacy policy: https://keydealer.ru/legal/privacy