First steps

Evrona is compatible with the OpenAI API: if you already have code on the official SDK, change the address and the key and it will work.

1. 01

   Create an account

2. 02

   Put money on the balance and issue an API key in the dashboard.

3. 03

   Insert the key into the snippet below and send the request.

curl https://evrona.ru/v1/chat/completions \
  -H "Authorization: Bearer ev-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hi there!"
      }
    ]
  }'

Pick a model: its ID and the right endpoint drop into the code by themselves. The highlight shows the one and only place your key lands — issue it in the dashboard, on the keys page, and put it in place of the placeholder.

The base_url is the address above with the /v1 suffix appended. Which model answers is decided by the model parameter.

The Model ID is copied from the catalogue whole, without cutting the part before «/»: say, google/gemini-3.7-flash or anthropic/claude-sonnet-4.6.

How to connect an app

Three values are enough to set up any app with an OpenAI-compatible API (Claude Code and the Anthropic SDK fall outside this: they speak a protocol of their own, see the card below):

When the field is just «Base URL», the app will append /chat/completions on its own — there is no need to write it by hand. And check that the address has not turned into /v1/v1.

Checking the key without any app is easy: send the request from the First steps block above.

Step-by-step guides

• Claude Code
• Codex CLI
• AAider
• Qwen Code
• OpenCode
• Hermes Agent
• Cursor
• Cline
• n8n
• Telegram Bot
• OpenClaw
• LangChain
• LlamaIndex

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "Evrona": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Evrona",
      "options": {
        "baseURL": "https://evrona.ru/v1",
        "apiKey": "ev-YOUR_KEY"
      },
      "models": {
        "openai/gpt-5.4-mini": { "name": "GPT-5.4 Mini" },
        "anthropic/claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" }
      }
    }
  }
}

Text chat — the model’s answer

A model answer to a conversation. Handles stream=true (SSE). Request and response formats are the same as OpenAI’s.

To turn the stream on, pass "stream": true. Chunks go as data: {...}, and at the end comes data: [DONE].

What works: text chat together with tool calls via tools and tool_choice, image input on models that have the capability, creating and editing images, creating video. In chat, response_format, functions, audio and modalities give 400 as before: we will not swallow a parameter silently.

Fields of the chat request

This is the body of POST /v1/chat/completions. There are just two required fields, model and messages; the rest may be omitted, since each has a sensible default.

What the answer holds

The shape is the same as OpenAI’s, so the official SDKs parse it without any changes.

Images in a request

A model able to look at pictures takes them right inside the conversation: a screenshot of an error, a photo of a receipt, a mockup. No separate endpoint is needed — the frame travels as a part of the message next to the text, in the same POST /v1/chat/completions. On /v1/messages and /v1/responses it is exactly the same.

How to attach an image

In a user message, content turns into an array of parts: text is a part of type text, an image is a part of type image_url where url is a string shaped like data:image/png;base64,… — the image type plus its bytes in base64. The order of parts does not change: the model sees them exactly as you sent them. The detail field (auto, low, high) goes to the model as is. A message may consist of images alone, with no text at all.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What text is on this screenshot?" },
    {
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…", "detail": "auto" }
    }
  ]
}

The gateway does not pull remote links: an image behind http or https will return 400 invalid_request with a hint. Turn the file into base64 on your side — in any language that is a single line of code.

curl https://evrona.ru/v1/chat/completions \
  -H "Authorization: Bearer ev-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": [
      { "type": "text", "text": "What text is on this screenshot?" },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,'"$(base64 -w0 shot.png)"'" } }
    ]}]
  }'

What is allowed

• Formats: PNG, JPEG, WebP. The type is read from the first bytes of the file rather than from its name: a "png" with something else inside gets 400 right here and never reaches the model.
• Per image — no more than 5 MB of binary data; in base64 the same file swells by about a third.
• No more than 50 images per request, and every image of the conversation counts, not only those in the last message.
• A request body with images — no more than 24 MB. This cap outranks the image count: 50 of them get through only if they are small.
• A body larger than 2 MB is read only under a working key with a positive balance, and the upload is given 30 s — past that comes 408 request_timeout with a Retry-After header. Only a limited number of large uploads run at once: the next one will get 429 with Retry-After, so repeat it after the stated delay.
• Above 20 images in one request some models take only small ones — up to 2000 px on the longer side.

Which of the models look at pictures

The capability is confirmed by a live probe rather than by a promise: today 40 models of the catalogue accept images. The same ones carry the "Understands images" mark on the Models page, and GET /v1/workspace/rates returns them in the capabilities field. A model without the capability answers 400 unsupported_capability and is never charged.

What a picture ends up costing

An image is billed as the model’s input tokens, and how many there are is the model’s own call: usually on the order of 1 089 tokens for a 1024×1024 frame, several times more on some models. We charge exactly what the model returned in usage.prompt_tokens — the formula is the same as for text. A reserve with a margin is set aside for the request and the surplus returns to the balance (see Rates and charges). An estimate of the same order is handed back by POST /v1/messages/count_tokens.

Pictures coming from an agent

An image produced by a tool result — the agent opened an image file or grabbed a screenshot — gets through to the model as well. In the OpenAI protocol a tool result carries text alone, so the gateway sends such images on as a separate user turn right behind the series of results, and the order of the conversation does not suffer for it. There is nothing to configure.

On /v1/responses an image is an input_image part, and detail: original counts as high. On /v1/messages it is an image block with a base64 source; a url source is not pulled, just as in chat. document and file blocks still give 400: file input is not accepted yet.

When a rejection comes

400 invalid_request — the format is wrong, the bytes do not match the declared type, the size or count of images is exceeded, an image ended up in a system, developer or assistant message. 400 unsupported_capability — the model takes no images. 400 context_length_exceeded — the images together with the text do not fit the model context. 408 request_timeout — the body was not read in full within the allotted time. 413 payload_too_large — the body went past the limit. Not one of these rejections is billed.

Creating images

POST /v1/images/generations works synchronously, and its request and response are OpenAI Images-compatible. You are charged a fixed price for one image, multiplied by the count (n).

curl https://evrona.ru/v1/images/generations \
  -H "Authorization: Bearer ev-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "a red cat wearing glasses",
    "n": 1
  }'

The model must be an image model (see GET /v1/models). The response is a data array, each item carrying b64_json: the frame as base64. We never hand out a link, even when the model returns one — the frame arrives as bytes. Token-priced models also return usage: exactly the numbers you were charged for. The x-request-id response header is the id of the charge record, so the request can be found in GET /v1/workspace/spend.

The prompt may be at most 15 000 characters long. Generation does not take the fields image, images, mask, aspect_ratio, image_size, resolution: the answer will be 400 unsupported_parameter. If you need an image on the input, call POST /v1/images/edits instead.

Editing an existing picture

POST /v1/images/edits reworks an existing image from a text prompt: swap the background, add a detail, follow a style. The body goes as multipart/form-data, after the OpenAI Images API: one file or several, plus a prompt. What comes back is a base64 frame.

curl https://evrona.ru/v1/images/edits \
  -H "Authorization: Bearer ev-YOUR_KEY" \
  -F model=openai/gpt-image-2 \
  -F prompt="Swap the background for a light gradient" \
  -F image=@cat.png

In response:

{
  "created": 1757700000,
  "data": [{ "b64_json": "iVBORw0KGgo…" }],
  "usage": { "input_tokens": 116, "output_tokens": 1650, "total_tokens": 1766 }
}

The format of the frame is the model’s to choose: one returns PNG, another JPEG. We neither promise nor re-encode it — read data[0].b64_json as image bytes and, if you need the type, detect it from the first bytes.

The usage field is far from always present: a per-frame model returns none at all — you pay for the frame, not for tokens. The input_tokens_details and output_tokens_details breakdown shows up only when the model supplied it, so check whether the field is there rather than counting on it.

Form fields

Taken, yet not passed to the model

quality, user, background at opaque or auto, input_fidelity at low. A request with these fields will go through, but the result and the price come out the same as without them.

Timings and parallel requests

An edit takes anywhere from one to several minutes. We wait for the model up to 570 seconds and then answer 504 upstream_timeout with no charge — so set your own client timeout no lower than 600 seconds. Parallel edit requests from one account: 2; the next one will get 429 with a Retry-After header. After 5 rejected requests in a row (400), editing for the account freezes for about a minute, so it is wiser to check the prompt length and field values before sending.

Rates and charges

The price is the same as generation on this model: there is no separate tariff for editing. On a token-priced model input and output are counted at its rates, and usage in the response shows exactly the numbers the charge went by. On a per-frame model the price of a frame is multiplied by the number of frames. A reserve with a margin is set aside for the request, the surplus returns, and a model failure costs nothing.

The Content-Length header is required: an upload without it (chunked) will return 400 invalid_request. When your client hands the file over as a stream, read it into memory or set the size yourself.

The response carries an x-request-id header — the id of the charge record. It finds the request in GET /v1/workspace/spend (the id field) and in the dashboard; the OpenAI SDK exposes it as request_id.

Which of the models can edit

Editing is enabled on 2 models of the catalogue today. They carry the "Editing" mark on the Models page, and GET /v1/workspace/rates returns the image_edit capability in the capabilities field.

Creating video

Video is assembled asynchronously: the request files a job and hands back its id at once. The seconds parameter must be passed — it is the clip length, and the price is computed from it.

curl https://evrona.ru/v1/videos/generations \
  -H "Authorization: Bearer ev-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba/wan-2.6",
    "prompt": "a paper boat drifting on a calm pond",
    "seconds": 5
  }'

# {"id": "9b2f…", "status": "processing", "created": 1755648000}

curl https://evrona.ru/v1/jobs/JOB_ID \
  -H "Authorization: Bearer ev-YOUR_KEY"

# {"id": "9b2f…", "status": "succeeded", "url": "https://…/clip.mp4"}

The price of a request is the per-second rate multiplied by seconds. The money goes into a reserve when the job is filed and is debited only once the clip is ready; if generation fails, the reserve comes back in full.

Models and allowed durations

You need a model of type “video” — GET /v1/models lists them. Per-second rates are on the models page.

A clip is assembled from text only. A photo as the first frame is not something we can do yet: a request with any of the fields image, images, image_url, input_reference, first_frame, last_frame, reference_images will get 400 unsupported_parameter, and nothing is charged.

Endpoint reference

Rates and charges

How the billing works

• Money goes onto the balance in advance: there are no month-end invoices and no subscriptions here.
• Each request costs exactly its own amount: the price comes out of the model and the number of tokens.
• The balance goes down immediately after the answer. If the money ran short, the request comes back with 402: the account never goes negative.

Where the amount comes from

Every model carries its own price per 1 million tokens, and it differs for input (your request) and output (the model’s answer). Output almost always costs more than input. Current prices for all models are gathered in the Models and pricing catalogue.

in   =  tokens_in   / 1 000 000 × price_in
out  =  tokens_out  / 1 000 000 × price_out
───────────────────────────────────────────
sum  =  in + out

Both halves are rounded up to a millionth of a dollar. The token counts arrive from the model’s own answer — that very usage field you can see in your code.

A sample calculation

model — openai/gpt-5.4-mini · input at $0.1188 for 1M tokens · output at $0.6336 for 1M tokens

The prices above are not invented: they come from the live catalogue — the same one that feeds the bill.

The discounted cache rate

When a request opens with the same text as the previous one — a system prompt, instructions, a long context — the model pulls that opening from its cache, and we bill those tokens at a discounted rate. Nothing needs switching on: the cache fires by itself as soon as an identical prefix arrives back to back and is long enough, roughly a thousand tokens or more. The first request, the one that writes the cache, costs not a cent extra: it is billed just as it would be without a cache.

in  =  (tokens_in − tokens_cached) / 1 000 000 × price_in
    +  tokens_cached / 1 000 000 × rate_cache_in

The number of tokens served from cache is in the response: usage.prompt_tokens_details.cached_tokens, or usage.cache_read_input_tokens on the /v1/messages endpoint. The same figures appear in the dashboard, in GET /v1/workspace/spend and in the CSV export. The cached-input rate is listed on the Models page and in GET /v1/workspace/rates. Not every model gets the discount: where no rate is listed, the cache is billed at the regular input price.

The reserve while the request is running

While the model is typing, the length of the answer is unknown to anyone. So even before we call the model, the worst case is set aside on your balance:

reserve  =  tokens_in / 1 000 000 × price_in
         +  max_tokens / 1 000 000 × price_out

If there is not enough for the reserve, the request is turned down at once, never reaching the model. And once the answer is in, the actual cost is charged and the remainder of the reserve returns to the balance in the same instant.

Keep max_tokens near the answer length you expect: the higher it is, the larger the reserve and the less balance remains for parallel requests. When max_tokens is not set, the reserve is computed against the 32,000-token ceiling.

Cases with no charge at all

An error on the model’s side (502, 504) costs nothing, and the reserve returns in full. A turned-down request — wrong key, empty balance, an unsupported field, an oversized body — is free as well, since it never made it to the model. And token estimation via /v1/messages/count_tokens is free at all times.

Where the spend is visible

In the dashboard. The key page keeps a log of requests — model, tokens and cost for each — and next to it a CSV export and a daily chart. The spend section holds a summary for the period with a breakdown by model. We never store the text of requests or answers, so the statistics hold nothing but these counters.

Account API — balance, rates and spend per key

A read-only API for the account: pull balance, retail prices and key usage straight from your own backend, without opening the dashboard. The base URL and ready-made snippets are gathered in the "Account management" section of the dashboard.

Authorize with the very key you call models with: the Authorization: Bearer header. GET is the only method allowed; the key has to be active — paused and revoked ones answer 401. Do not place the key in a URL, and certainly not in browser code. Statistics are counted for the key that made the request, while balance and prices are shared across the whole account.

Query-string parameters

None of the parameters is required. A value outside the allowed range gives 400 invalid_request, with the parameter name arriving in param.

Sample requests

curl https://evrona.ru/v1/workspace/balance \
  -H "Authorization: Bearer ev-YOUR_KEY"

# {"object": "workspace.balance", "balance_usd": 4.981234, "currency": "USD"}

curl "https://evrona.ru/v1/workspace/spend?days=7&limit=25" \
  -H "Authorization: Bearer ev-YOUR_KEY"

In response:

{
  "object": "list",
  "days": 7,
  "limit": 25,
  "page": 0,
  "has_more": false,
  "data": [
    {
      "id": "9b2f…",
      "created_at": "2026-08-21T09:58:12.000Z",
      "model": "openai/gpt-5.4-mini",
      "operation": "chat",
      "status": "success",
      "tokens_in": 1200,
      "cached_tokens_in": 0,
      "images_in": 0,
      "tokens_out": 800,
      "cost_usd": 0.00065,
      "price_input_usd_per_1m_tokens": 0.1188,
      "price_cached_input_usd_per_1m_tokens": 0.0168,
      "price_output_usd_per_1m_tokens": 0.6336,
      "price_generation_usd": null,
      "latency_ms": 812
    }
  ]
}

The /v1/workspace/insights response is a single object with:

totals · models[] · daily[] · errors.by_code[]

Possible errors

The error envelope is the same across the whole gateway — it is unpacked in the Request errors section. In this API you may run into:

401 invalid_api_key · 400 invalid_request · 429 rate_limited

Limits and caps

The limits guard your balance as much as the gateway: a stray loop in your code must not burn the money up in a minute.

Going over the rate brings 429 rate_limited: wait and retry — the key is not blocked and not penalised for it. A body larger than 2 MB is read only under a working key with a positive balance: the upload is given 30 s, and only a limited number of large uploads run at once — an extra one will get 429 with a Retry-After header. The money limit and the schedule are yours to set, in the dashboard on the key page. Guessing at wrong keys from one address we throttle on top of that.

Characters are counted, not bytes: a Cyrillic letter is one, an emoji usually two.

How patient the gateway is with the model. In chat — up to 280 seconds before the answer starts and up to 240 seconds of silence in the middle. For image requests — up to 570 seconds. If the answer has not begun within that span, 504 upstream_timeout comes back and nothing is charged. Without stream the answer arrives in one piece, so on long answers stream is better switched on. If the answer broke off midway, or your client closed the connection ahead of time, the request lands in the log with the status aborted: you pay for the processed request and for the part of the answer that got through. Set the timeout on your side above these numbers.

The /uptime page shows availability and average response time of every model by hour.

Gateway error codes

All errors share one shape, the same as OpenAI’s, so the SDKs parse them without your help:

{
  "error": {
    "message": "No enabled model matches that name. Request GET /v1/models to see what is available.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Rely on code: it is machine-readable and stays as it is. The message text is written for a human and may be rewritten over time. When the error sits in a specific request field, param points at it.

We take no money for anything in this table. A request that never made it to the model, and a request the model answered with an error, are both uncharged, and the reserve goes back to the balance in full.

Questions and answers