# everyais API and public data reference

<a id="answer-first"></a>
## Answer first

everyais is an OpenAI-compatible AI API gateway: one API key and base URL provide access to the callable models in its public catalog, with usage controls and transparent reference costs.

Updated: 2026-09-10T22:16:00.967Z

<a id="definitions"></a>
## Definitions

- Reference price: the public catalog price, including model discounts, used for comparison; account and organization rates can change the final billed price.
- Usage ranking: input + output tokens that actually passed through everyais, not vendor claims or estimates.
- Benchmark: a score reproduced from a named external source; everyais does not re-measure that score.

<a id="model-catalog"></a>
## Model catalog

Source: https://api.everyais.com/models/catalog
- English: https://platform.everyais.com/en/models
- 한국어: https://platform.everyais.com/models
- `everyais/gpt-6-astra`
- `everyais/claude-fable-5-1`
- `everyais/claude-opus-5`
- `everyais/claude-sonnet-5`
- `everyais/gemini-omni-flash-preview`
- `everyais/gemini-3-1-flash-lite-image`
- `everyais/gpt-5-6-luna`
- `everyais/gpt-5-6-sol`
- `everyais/gpt-5-6-terra`
- `everyais/claude-fable-5`
- `everyais/claude-opus-4-8`
- `everyais/gemini-3-1-flash-image`
- `everyais/gemini-3-5-flash-lite`
- `everyais/google-gemma-4-31b`
- `everyais/google-gemma-4-e2b`
- `everyais/google-gemma-4-26b-a4b`
- `everyais/deepseek-v4-pro-0813`
- `everyais/deepseek-v4-flash-0731`
- `everyais/gemini-3-1-pro-preview-customtools`
- `everyais/gemini-3-1-pro-preview`
- `everyais/glm-5-3-flash`
- `everyais/glm-5-2`
- `everyais/gemini-3-pro-image`
- `everyais/claude-haiku-4-5`
- `everyais/veo-3-1-lite-generate-001`
- `everyais/veo-3-1-fast-generate-001`
- `everyais/veo-3-1-generate-001`
- `everyais/gemini-2-5-flash-image`
- `everyais/gemini-2-5-flash`
- `everyais/gpt-image-2-5-sunburst`
- `everyais/gpt-image-2-5-flare`
- `everyais/gemini-omni-1-1-flash`
- `everyais/gemini-3-8-flash`
- `everyais/muse-spark-1-2`
- `everyais/muse-spark-1-2-contributor`
- `everyais/muse-image-1-0`
- `everyais/kimi-k3`
- `everyais/minimax-m3`
- `everyais/nemotron-3-5-lightning`
- `everyais/gemini-3-7-flash`

<a id="rankings-methodology"></a>
## Rankings methodology

The denominator is all input + output tokens in the selected period. Trend and generation-speed values are published only with at least 100 measured requests in the relevant sample; unavailable never means zero.
Source: https://api.everyais.com/models/rankings
- English: https://platform.everyais.com/en/rankings
- 한국어: https://platform.everyais.com/rankings

<a id="benchmark-provenance"></a>
## Benchmark provenance

The catalog separates benchmark definitions and licensed sources. Only active sources joined through human-approved model mappings are publishable. Each row keeps its source URL, source license, measured date, and vendor-reported status so independent and vendor-reported scores stay distinguishable.
Source: https://api.everyais.com/models/benchmarks/catalog
- English: https://platform.everyais.com/benchmarks
- 한국어: https://platform.everyais.com/ko/benchmarks

<a id="api-docs"></a>
## API docs

- Base URL: https://api.everyais.com/v1
- Authentication: `Authorization: Bearer everyais_...`
- OpenAPI: https://api.everyais.com/openapi.json
- English: https://platform.everyais.com/en/docs
- 한국어: https://platform.everyais.com/docs

# Getting started

## Quickstart

_Send your first request with curl, Python, or Node.js._

Source: https://platform.everyais.com/en/docs/quickstart
Updated: 2026-09-08T10:12:12.305Z

## 1. Prepare an API key

[Create a key in the dashboard](/dashboard/keys) and [add credits](/dashboard/pricing).
The plaintext key is shown only once. Set it as an environment variable in your terminal.

```bash
export EVERYAIS_API_KEY="everyais_your_api_key"
```

## 2. Choose a model

```bash
curl https://api.everyais.com/v1/models \
  -H "Authorization: Bearer $EVERYAIS_API_KEY"
```

From `data`, choose a model with `category: "LLM"` and `available: true`, and copy its exact `id`.
If your key restricts scopes, it needs `models:read` for listing and `chat` for generation.

```bash
export EVERYAIS_MODEL="model_ID_copied_from_the_catalog"
```

Model IDs and capabilities can change. See [model selection](./model-selection) for capabilities and access policies.

## 3. Send your first request

### curl

```bash
curl https://api.everyais.com/v1/chat/completions \
  -H "Authorization: Bearer $EVERYAIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$EVERYAIS_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],
    \"max_tokens\": 1024
  }"
```

### Python

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.everyais.com/v1",
    api_key=os.environ["EVERYAIS_API_KEY"],
    timeout=240.0,
)
response = client.chat.completions.create(
    model=os.environ["EVERYAIS_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=1024,
)
print(response.choices[0].message.content)
```

### Node.js

```bash
npm install openai
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.everyais.com/v1",
  apiKey: process.env.EVERYAIS_API_KEY,
  timeout: 240_000,
});
const response = await client.chat.completions.create({
  model: process.env.EVERYAIS_MODEL,
  messages: [{ role: "user", content: "Hello!" }],
  max_tokens: 1024,
});
console.log(response.choices[0].message.content);
```

## Next steps

| Goal | Documentation |
|------|---------------|
| Display tokens as they arrive | [Streaming](./streaming) |
| Connect Claude Code or the Anthropic SDK | [Messages](./messages) · [Integration](./integration-claude-code) |
| Generate text asynchronously | [Responses](./responses) |
| Generate or edit images | [Image generation](./images-generations) · [Image editing](./images-edits) |
| Generate video | [Video jobs](./videos-generations) |
| Handle a failed request | [Errors and retries](./errors-and-rate-limits) |

SDK configuration references: [Python SDK](https://github.com/openai/openai-python#usage) · [Node.js SDK](https://github.com/openai/openai-node#usage).

---

## Base URL

_The base URL for every request, the /v1 path rule, and request timeouts._

Source: https://platform.everyais.com/en/docs/base-url
Updated: 2026-09-08T10:12:11.403Z

## Base URL by client

| Client | Base URL |
|--------|----------|
| OpenAI SDK · Cursor · opencode | `https://api.everyais.com/v1` |
| Anthropic SDK · Claude Code | `https://api.everyais.com` |

OpenAI-compatible clients append paths such as `/chat/completions`, so include `/v1`.
The Anthropic SDK appends `/v1/messages` itself, so omit `/v1`.
Duplicating the prefix, such as `/v1/v1/messages`, returns 404.

## Configuring timeouts

There is no single guaranteed HTTP completion deadline across all API paths.
Response times depend on the model, input, provider-specific limits, waiting, and retries.
Set an explicit client timeout; if you lose the response, check the result and billing before retrying.

Streaming delivers output incrementally. Closing the connection does not guarantee immediate cancellation of
the provider's work or zero billing. Do not assume synchronous generation, images, or video share a streaming deadline.

Poll video jobs using their returned job ID, or set `background: true` for asynchronous Responses.
See [streaming](./streaming), [async jobs](./async-jobs), and [retry decisions](./errors-and-rate-limits).

## Request body size

| Request | Body limit |
|---------|------------|
| Chat · Messages · Responses | 5 MiB |
| Image editing — entire multipart body | 4 MiB |
| Image editing — JSON | 5 MiB |
| General requests, including image and video generation | 1 MiB |

Exceeding a limit returns 413 `request_too_large`. One MiB is 1,048,576 bytes.
Multipart boundaries and fields count toward the body limit along with the files.

## Public resources

The [OpenAPI spec](https://api.everyais.com/openapi.json), [documentation index](/llms.txt),
and [full documentation](/llms-full.txt) are available without authentication.
Browse the [model directory](/models), then use `GET /v1/models` to find models available to your key.

---

## Authentication

_Issuing API keys, the Bearer header, and per-key limits and scopes._

Source: https://platform.everyais.com/en/docs/authentication
Updated: 2026-09-08T10:12:11.854Z

Pass your API key in the header for inference and `/v1/models` requests.

```
Authorization: Bearer everyais_your_api_key
```

You issue keys from the dashboard. Only the SHA-256 hash is stored on the server, so once you leave the screen right after issuing a key you cannot see the plaintext again.

## Per-key settings

| Setting | Description |
|------|------|
| Rate limit | 100 req/min by default. Adjustable when you create or edit the key |
| Monthly/daily/per-minute spend limit (USD) | 402 `spend_limit_exceeded` when exceeded |
| Allowed models | When set, calls to models outside that list return 403, and `GET /v1/models` results are filtered to that list as well |
| Scopes | `chat` · `images` · `video` · `models:read`. Calls outside a scope return 403. Leave them all empty to allow everything |
| Expiry date | When set, requests return 401 after expiry |

## Authentication methods and account scope

The Anthropic SDK's `x-api-key: everyais_...` header is also accepted.
If both headers are supplied, a valid Bearer-formatted `Authorization` header takes precedence.
Keep keys in environment variables and make calls from your server, never from public browser code or repositories.

API keys authorize inference and reads for consumer accounts. Account settings, payments, and key management
require a signed-in user session; an API key returns 403 `api_key_session_forbidden`.
Supplier accounts cannot use consumer APIs (403 `account_kind_forbidden`).

Organization keys use the organization's credits and policies, including community supply and training-use consent.
See [model selection and access policies](./model-selection).

---

## Model selection and access

_Model IDs, capabilities, routing, and account or organization access policies._

Source: https://platform.everyais.com/en/docs/model-selection
Updated: 2026-09-10T15:37:02.328Z

## 1. Find models available to your key

`GET /v1/models` applies the key's allowed-model list and account or organization policies.
The public [model directory](/models) also displays models that need consent, so its list can differ from your key's list.
Use the exact `id` returned by the API.

## 2. Check capabilities

| Field | Purpose |
|-------|---------|
| `category` | `LLM` / `IMAGE` / `VIDEO` |
| `supported_endpoints` | Public paths associated with the model |
| `capabilities.streaming` · `tool_use` · `vision` · `json_mode` | Streaming, tools, image inputs, and JSON output requests |
| `capabilities.web_search` | Server-side web search through Chat |
| `capabilities.json_mode_with_tools` · `web_search_with_tools` | Support for JSON+tools and web search+function tools |
| `capabilities.sampling` · `structured_outputs` · `parallel_tool_calls` · `image_mask` | Sampling, strict schemas, parallel-call control, and mask support |
| `limits.reasoning_efforts` · `supported_sizes` · `supported_qualities` · `supported_durations` · `max_images` | Model-specific values and counts. Omitted fields mean unverified support |
| `limits.max_tokens` · `context_window` | Model-specific output and context limits |
| `available` | Current catalog availability |

Model-specific parameter limits may be lower than the gateway's common limits.
Messages and Responses use chat compatibility translation; they do not expose every upstream feature.

## 3. Check access policies

Community supply (`supply`) and provider training use (`training_use`) require separate consent, both off by default.
Personal keys use account settings; organization keys use organization settings.

| Required consent | No callable candidate in Chat, Messages, or Responses |
|------------------|-----------------------------|
| Community-only model | 404 `model_not_found` |
| Training-only model | 404 `model_not_found` |

`mixed` models use only permitted endpoints. If a model is missing, check the key's allowed models,
both consent settings, and the model's active status.

## 4. Routing hints

Chat requests accept `provider: {"sort": "latency", "allow_fallbacks": true}`.
`sort` accepts `price`, `latency`, or `throughput`; `allow_fallbacks` controls retries across supply routes.
The former provider-name selectors `only`, `order`, and `ignore` have been retired and are ignored.

The `models` array accepts up to 5 fallback model IDs. Fallback happens only before credit reservation
when the selected model is unavailable. It does not continue a failed generation using another model.

Public token prices use one eligible route's input/output pair with the lowest combined rate; billing applies account rates. Check `pricing.conditions` for consent needed by these rates. See [model and pricing fields](./models).

---

# Endpoints

## POST /v1/chat/completions

_OpenAI-compatible chat completions. Supports streaming, tool calls, and structured outputs._

Source: https://platform.everyais.com/en/docs/chat-completions
Updated: 2026-09-08T10:12:12.754Z

Chat completions (LLM). Set `stream: true` for token-by-token SSE streaming.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | Model ID (e.g. `everyais/claude-opus-5`) |
| `messages` | array | Yes | Array of 1–1000 messages. `role` is `system` / `user` / `assistant` / `tool` / `developer` (normalized to system). `content` is a string, null, or an array of multimodal parts (up to 1000) |
| `stream` | boolean | No | SSE streaming (default `false`) |
| `stream_options` | object | No | With `{"include_usage": true}`, the final chunk includes usage |
| `max_tokens` | integer | No | Maximum output tokens, 1–200000. `max_completion_tokens` is normalized automatically |
| `temperature` | number | No | 0–2 |
| `top_p` | number | No | 0–1 |
| `stop` | string \| string[] | No | Up to 4 |
| `n` | integer | No | **Only 1 is supported** (default 1). 2 or more returns 400 |
| `presence_penalty` / `frequency_penalty` | number | No | -2–2 |
| `seed` | integer | No | Reproducibility hint |
| `tools` | array | No | Function tool definitions (up to 512) and the server-side web search `{"type":"web_search"}` (up to 1 — see the web search guide) |
| `tool_choice` | string \| object | No | `auto` / `none` / `required`, or `{"type":"function","function":{"name":"..."}}`. `none` also disables web search |
| `response_format` | object | No | `{"type":"text"}` · `{"type":"json_object"}` · `{"type":"json_schema","json_schema":{...}}` |
| `reasoning_effort` | string | No | `none` / `low` / `medium` / `high` |
| `parallel_tool_calls` | boolean | No | Allow parallel tool calls |
| `logprobs` / `top_logprobs` | boolean / integer | No | Forwarded on Chat Completions routes that support them. `top_logprobs` is 0–20. Explicit values return 400 on OpenAI/Mantle upstream Responses routes |
| `user` | string | No | End-user identifier |
| `everyais` | object | No | Gateway options — `{"cache":"on"\|"off","cache_ttl":"5m"\|"1h"}` and `provider` |
| `provider` | object | No | Routing hints: `sort` (`price` / `latency` / `throughput`) and `allow_fallbacks`. Selecting providers by name is not supported. |
| `models` | string[] | No | Catalog fallback, max 5. Tried before reservation when the first model is not callable. |
| `extra_body` | object | No | Provider-specific extensions — only the `anthropic` / `google` / `openai` / `everyais` keys are allowed (any other key returns 400). `extra_body.provider` is rejected. |

You may append `:nitro` (prefer lower latency) or `:floor` (prefer lower endpoint cost) to a model slug. Billing does not change.

Undefined OpenAI parameters (`logit_bias`, `store`, etc.) are silently ignored.

## Model-specific options

The table above describes the shared input schema, not universal model support. Check `capabilities` and `limits` in `GET /v1/models`. `false` means unsupported; an omitted field means support is unverified. Explicit unsupported options, values, and combinations return **400**.

| Model / route | Supported values and combinations |
|---------------|-----------------------------------|
| Claude Opus 5 and other latest Claude / Bedrock | Omit `temperature`, `top_p`, and `extra_body.anthropic.top_k`; explicit values return 400. `reasoning_effort` values `low`/`medium`/`high` use adaptive thinking and effort, without converting them into manual `budget_tokens` |
| Claude Opus 4.6 / Sonnet 4.6 | Support both adaptive and manual thinking. Manual budgets require `1024 ≤ budget_tokens < max_tokens` |
| Claude 3.7 Sonnet / Opus 4, 4.1, 4.5 / Sonnet 4, 4.5 / Haiku 4.5 | Support manual thinking. `reasoning_effort` requests thinking budgets of 2048 (`low`), 8192 (`medium`), or 32768 (`high`); this budget is added to `max_tokens` in the provider request |
| Claude Fable / Mythos | Disabling reasoning with `reasoning_effort: "none"` returns 400 |
| Gemini 3.6, 3.7, 3.8 Flash / 3.5 Flash-Lite | Explicit `temperature`, `top_p`, or `extra_body.google.top_k` returns 400. Omission uses the provider default |
| Gemini 3.1 Flash Image / Flash-Lite Image (Chat) | Only explicit `reasoning_effort: "high"` is supported. See image endpoint documentation for size and quality |
| Gemini 3 Pro | Supports `low`/`high`; `medium`/`none` return 400 |
| Gemini 3.1 Pro / Gemini 3 Flash, 3.1 Flash-Lite, 3.5 Flash | Supports `low`/`medium`/`high`. `none` returns 400 and is never changed to `low` |
| Gemini 2.5 Pro | Thinking budgets: `low`=2048, `medium`=8192, `high`=32768 tokens; `none` returns 400 |
| Gemini 2.5 Flash / Flash-Lite | Thinking budgets: `none`=0, `low`=2048, `medium`=8192, `high`=24576 tokens |

- With thinking enabled on Claude 4.6 and earlier, explicit `temperature` must be 1, `top_p` must be 0.95–1, and `top_k` returns 400. Opus/Sonnet 4.5 and 4.6, plus Haiku 4.5, also reject specifying both `temperature` and `top_p`. Manual thinking cannot be combined with `tool_choice: "required"` or a named function. Fable/Mythos 5.1 does not support forced tool selection at all.
- Chat `max_tokens` can be capped at the model's output limit. A manual budget supplied directly through `extra_body.anthropic.thinking` is not added to `max_tokens`; it must be smaller than `max_tokens`.
- An OpenAI-compatible request format does not imply identical options across provider routes. OpenAI/Mantle **upstream Responses routes** (including GPT-6 and Responses-only models) return **400** for explicit `stop`, `seed`, `presence_penalty`, `frequency_penalty`, `logprobs`, or `top_logprobs`. Even `logprobs: false` differs from omission. These options are not silently ignored; `user` is forwarded unchanged as the end-user identifier. This provider-route restriction also applies when your public endpoint is `/v1/chat/completions`.
- `capabilities.sampling` describes sampling support; `limits.reasoning_efforts` lists the model's reasoning levels. Omission uses the model default and differs from `none`.
- `json_mode` means JSON output requests; `structured_outputs` means native strict schema support. Claude `json_object` and JSON schemas with `strict` omitted or `false` use a best-effort prompt and do not guarantee schema compliance. `strict: true` requires native support; otherwise it returns 400. Claude `function.strict` also requires native support.
- Strict function tools have separate support requirements from JSON schemas. Gemini 3 `function.strict: true` uses the provider's `VALIDATED` mode for automatic tool selection. Gemini 2.5 supports JSON schemas but rejects strict function tools (`strict: true`) with 400.
- Claude native strict support depends on the route. Bedrock supports Opus/Sonnet 4.5 and 4.6, plus Haiku 4.5; this does not automatically extend to Opus 5. Rely on support only when the public capability is `true`.
- Claude honors `parallel_tool_calls: false` by disabling parallel tool use. Gemini rejects `false` with 400; `true` or omission allows the provider's parallel calls.
- Gemini 2.5 rejects combining JSON output (`json_object`/`json_schema`) with tools, and rejects mixing web search with function tools, with 400. Use those features separately. Gemini 3 supports these combinations. `capabilities.json_mode_with_tools` and `web_search_with_tools` are `false` for unsupported combinations; omission means unverified support.
- In a function-tool loop, replay the original assistant `tool_calls` unchanged to the **same model**, followed by the tool result for its `tool_call_id`. Gemini `tool_calls[].extra_content.google.thought_signature` is opaque provider state; do not modify it, strip it, or reuse it with another model.
- `web_search` is available only on Chat models with `capabilities.web_search: true`. Gemini `tool_choice: "none"` also disables search. Requiring a tool or naming a function when only a search tool is present returns 400.

## Request

```json
{
  "model": "everyais/claude-opus-5",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "max_tokens": 1024
}
```

## Response

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709884800,
  "model": "everyais/claude-opus-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 10,
    "total_tokens": 35
  }
}
```

## Streaming

With `stream: true`, `data: {...}` SSE chunks follow one another and end with `data: [DONE]`.
Enabling `stream_options.include_usage` appends a final usage chunk.

See the [streaming guide](./streaming) for a complete example and completion/error handling.

---

## POST /v1/messages

_Anthropic Messages compatible endpoint and free token counting._

Source: https://platform.everyais.com/en/docs/messages
Updated: 2026-09-08T10:12:13.206Z

Anthropic Messages compatible — anthropic-native clients such as Claude Code connect as-is.
Internally it runs through the same chat pipeline and supports `stream`.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | Model ID |
| `messages` | array | Yes | `role` is `user` / `assistant`. content is a string or an array of blocks (text, image, tool_use, tool_result, thinking, document) |
| `max_tokens` | integer | Yes | 1–200000 (required by the Anthropic spec) |
| `system` | string \| array | No | A string or an array of text blocks |
| `temperature` | number | No | 0–1 |
| `top_p` | number | No | 0–1 |
| `top_k` | integer | No | Positive integer |
| `stop_sequences` | string[] | No | Up to 8 |
| `stream` | boolean | No | Defaults to `false` |
| `tools` | array | No | `{name, description, input_schema}` |
| `tool_choice` | object | No | `{"type":"auto"\|"any"\|"none"}` or `{"type":"tool","name":"..."}` |
| `metadata` | object | No | `{"user_id": "..."}` |
| `thinking` | object | No | `{"type":"enabled","budget_tokens":N}` (N < `max_tokens`) · `{"type":"adaptive"}` · `{"type":"disabled"}` |
| `everyais` | object | No | Gateway caching options |

If you attach `cache_control` directly to a block, it is passed through as-is (see prompt caching).

## Model-specific thinking and tools

Check `capabilities` and `limits` in `GET /v1/models`. Omitted fields mean unverified support; unsupported options and combinations return **400**. See the model table under [Chat options](./chat-completions).

- Latest models such as Claude Opus 5 use `thinking: {"type":"adaptive"}`. Manual `thinking: {"type":"enabled","budget_tokens":N}` is not universal. Opus/Sonnet 4.6 support both modes.
- Manual budgets require `1024 ≤ budget_tokens < max_tokens`. Unsupported manual budgets are not resized or converted to adaptive thinking. Fable/Mythos reject `thinking: {"type":"disabled"}` with 400.
- Latest Claude on Bedrock rejects explicit `temperature`, `top_p`, and `top_k` with 400. Check `capabilities.sampling` before setting sampling options.
- `tool_choice.disable_parallel_tool_use: true` disables parallel calls. Claude native strict tools require `capabilities.structured_outputs: true`; for other models, see the strict function-tool restrictions in the Chat documentation; unsupported `strict: true` returns 400.
- Web search is exclusive to `/v1/chat/completions`. Messages tools are client-executed function tools.

## Request

```json
{
  "model": "everyais/claude-opus-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello!"}]
}
```

## Response

```json
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "everyais/claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 10
  }
}
```

---

## POST /v1/messages/count_tokens

Estimates the input token count before you send a request. Claude Code calls this endpoint automatically.

- **Free** — no credit is deducted.
- Returns a **heuristic estimate** without calling the upstream provider (it may differ from the exact tokenizer result).
- The request body takes the same shape as `/v1/messages`.

```json
{
  "input_tokens": 1234
}
```

---

## POST /v1/responses

_OpenAI Responses-compatible shim, including background job polling and cancellation._

Source: https://platform.everyais.com/en/docs/responses
Updated: 2026-09-08T10:12:13.657Z

OpenAI Responses compatible — a shim that converts the request into a chat request internally.
Anything like `previous_response_id` is **stateful storage, which is not supported**.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | Model ID |
| `input` | string \| array | Yes | A string, or an array of message / `function_call` / `function_call_output` items |
| `instructions` | string | No | system instructions |
| `max_output_tokens` | integer | No | Maximum output tokens |
| `temperature` | number | No | 0–2 |
| `top_p` | number | No | 0–1 |
| `stream` | boolean | No | Stream events token by token |
| `background` | boolean | No | If `true`, submits as an async job and returns `queued` immediately |
| `tools` / `tool_choice` | array / string\|object | No | Same format as chat |
| `reasoning_effort` | string | No | `none` / `low` / `medium` / `high` |
| `user` | string | No | End-user identifier |
| `everyais` | object | No | Gateway caching options |

## Model-specific options

The model restrictions in `GET /v1/models` `capabilities`/`limits` and [Chat options](./chat-completions) also apply here. Unsupported options, values, and combinations return **400**. Omit `temperature` and `top_p` when `capabilities.sampling: false`.

`reasoning_effort: "none"` is preserved as an explicit request to disable reasoning. It is not omitted or changed to `low`; models that cannot disable reasoning, including Gemini 3, return 400. Check `limits.reasoning_efforts` for supported levels.

Web search is exclusive to Chat; Responses `tools` supports function tools only. `response_format` and `parallel_tool_calls` are unsupported by this shim (explicit values return 400). Use Chat Completions for those options.

## Request

```json
{
  "model": "everyais/claude-opus-5",
  "input": "Hello!",
  "instructions": "Be concise."
}
```

## Response

```json
{
  "id": "resp_example",
  "object": "response",
  "created_at": 1709884800,
  "model": "everyais/claude-opus-5",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_example",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 10,
    "total_tokens": 35
  },
  "error": null,
  "incomplete_details": null,
  "max_output_tokens": null,
  "temperature": null,
  "top_p": null
}
```

---

## GET /v1/responses/{id}

Poll the status of a job submitted with `background: true`.

```json
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1709884800,
  "model": "everyais/claude-opus-5",
  "status": "queued",
  "output": [],
  "error": null,
  "incomplete_details": null,
  "usage": null
}
```

`status` transitions `queued` → `in_progress` → `completed` / `incomplete` / `failed` / `cancelled`.
Once it completes, the full stored Response body is returned.

Returns 404 if the job does not exist, has expired, or belongs to another key or user.

## POST /v1/responses/{id}/cancel

Transitions a job in `queued` or `in_progress` state to `cancelled` and refunds the reserved credit.
A job that has already finished is returned as its current Response with no status change.

---

## POST /v1/images/generations

_Image generation. n is at most 10._

Source: https://platform.everyais.com/en/docs/images-generations
Updated: 2026-09-08T10:12:14.110Z

Image generation.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | A model ID in the IMAGE category |
| `prompt` | string | Yes | 1–4000 characters |
| `n` | integer | No | Number of images to generate, **1–10** (default 1) |
| `size` | string | No | `256x256` · `512x512` · `1024x1024` · `1792x1024` · `1024x1792` · `1536x1024` · `1024x1536` · `auto` |
| `quality` | string | No | `standard` · `hd` · `low` · `medium` · `high` · `auto` — see model-specific values and omission defaults below |
| `response_format` | string | No | `url` (default) · `b64_json` |
| `user` | string | No | End-user identifier |

Some models have a lower limit on `n` (see the Imagen model notes).
For the image models you can use, check `GET /v1/models` for entries whose `category` is `IMAGE`.

## Model-specific size, quality, and count

Check `capabilities.image_generation`, `limits.max_images`, `limits.supported_sizes`, and `limits.supported_qualities` in `GET /v1/models`. Omitted fields mean unverified support. Even a value in the shared schema returns **400** when the model does not support it.

| Model | Supported values and meaning |
|-------|------------------------------|
| Native Gemini image | Supports only `n: 1`. Explicit `quality` returns 400. `auto`/omission uses provider defaults; `1024x1024` means 1:1, `1536x1024` means 3:2, `1024x1536` means 2:3, `1792x1024` means 16:9, and `1024x1792` means 9:16. These are **not guarantees of exact pixel dimensions** |
| Gemini 3 image | These aspect ratios use a 1K resolution request by default. `512x512` is supported only by Gemini 3.1 Flash Image; `256x256` is unsupported. Gemini 3.1 Flash-Lite Image supports 1K only |
| Gemini 2.5 image | Uses the provider's fixed native resolution. `256x256` and `512x512` are unsupported |
| Imagen | Regular generation supports `n: 1–4`; upscale uses the edit endpoint with 1. Explicit `quality` returns 400. Sizes are aspect-ratio aliases, not pixel guarantees: all three square sizes mean 1:1; `1536x1024` means 4:3, `1024x1536` means 3:4, `1792x1024` means 16:9, and `1024x1792` means 9:16 |
| OpenAI GPT Image | Supports `low`/`medium`/`high`/`auto`. `standard`→`medium` and `hd`→`high` are compatibility aliases. Omitted `quality` retains the existing `medium` default. Sizes are limited to `1024x1024`, `1536x1024`, `1024x1536`, and `auto`; omission uses `1024x1024`. `256x256` and `512x512` return 400 instead of being enlarged |
| Meta image | Explicit `quality` returns 400 |

## Request

```json
{
  "model": "<IMAGE model ID from GET /v1/models>",
  "prompt": "a beautiful sunset over mountains",
  "n": 1
}
```

## Response

```json
{
  "created": 1709884800,
  "data": [
    { "url": "https://..." }
  ]
}
```

`url` is a presigned URL valid for 10 minutes. To keep an image longer, download and store it yourself.
Once it expires you can re-issue one through `GET /v1/outputs/{requestId}` for up to 24 hours.

---

## POST /v1/images/edits

_Image editing (inpainting and outpainting). Supports both multipart and JSON (base64)._

Source: https://platform.everyais.com/en/docs/images-edits
Updated: 2026-09-08T10:12:14.566Z

Image editing. **Both** the official OpenAI SDK's `multipart/form-data` upload and a
JSON body (base64 string) are accepted.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | ID of a model that supports editing |
| `prompt` | string | Yes | 1–4000 characters |
| `image` | string \| file | Yes | Source image — a base64 string in JSON, a file part in multipart |
| `mask` | string \| file | No | Mask for the region to edit. Check `capabilities.image_mask` |
| `n` | integer | No | Number of images to generate, **1–4** (default 1) |
| `size` | string | No | `256x256` · `512x512` · `1024x1024` · `1792x1024` · `1024x1792` · `1536x1024` · `1024x1536` · `auto`. Only values supported by the selected model are accepted; omission uses the model default |
| `response_format` | string | No | `url` (default) · `b64_json` |
| `user` | string | No | End-user identifier |

The entire multipart body is limited to **4 MiB**; JSON is limited to **5 MiB**.
After file-to-base64 conversion, the payload must also fit within 5 MiB. Exceeding these limits returns
413 `request_too_large` or `invalid_request_error`. Check encoded byte size, not only image dimensions.

## Model-specific editing

Choose a model with `capabilities.image_editing: true` in `GET /v1/models`. `capabilities.image_mask` describes mask support. Omitted fields mean unverified support; unsupported options return **400**.

- Native Gemini image supports **prompt-based editing without a mask**. Explicit `mask` returns 400 and is never ignored. Only `n: 1` is supported. Size aliases have the same aspect-ratio/resolution meaning as [image generation](./images-generations).
- Imagen editing rejects explicit `size` with 400. Regular edits preserve the source size; upscale uses a 2× factor.
- Omitting `size` uses the model default; no shared `1024x1024` default is injected. Check `limits.supported_sizes` and `limits.max_images`, subject to the generation/editing differences documented here.

## Request (JSON)

```json
{
  "model": "<ID of a model that supports editing>",
  "prompt": "change the sky to sunset",
  "image": "<base64-encoded-image>",
  "n": 1
}
```

## Response

```json
{
  "created": 1709884800,
  "data": [
    { "url": "https://..." }
  ]
}
```

---

## POST /v1/videos/generations

_Video generation (billed per second). Submit, then fetch the result from the dedicated polling endpoint._

Source: https://platform.everyais.com/en/docs/videos-generations
Updated: 2026-09-08T10:12:15.018Z

Video generation is an **async job**. POST returns a job id immediately, and you poll
`GET /v1/videos/generations/{id}` for the result.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | A VIDEO category model ID (e.g. `everyais/veo-3-1-generate-001`) |
| `prompt` | string | Yes | 1–4000 characters |
| `duration` | integer | No | Shared input range: 1–120 seconds. Supported lengths and omission defaults depend on the model (see below) |
| `pricingVariant` | string | No | Resolution/audio variant key. Use the `pricing.variants[].key` value from `GET /v1/models` verbatim |
| `user` | string | No | End-user identifier |
| `extra_body.google` | object | No | `negativePrompt` (≤4000 characters) · `seed` · `enhancePrompt` |

## Model-specific duration and resolution

Check `capabilities.video_generation`, `limits.supported_durations`, and `pricing.variants[].key` in `GET /v1/models`. Omitted fields mean unverified support. Unsupported values and combinations return **400**, without silently replacing requested values.

| Model / route | Supported values and combinations |
|---------------|-----------------------------------|
| Veo 3 / 3.1 | `duration` supports **4, 6, or 8 seconds**, defaulting to 8 when omitted. `1080p` and `4k` require **8 seconds** |
| Veo 3.1 Lite | Supports 4, 6, or 8 seconds; `4k` is unsupported |
| Veo 2 | Supports **5, 6, 7, or 8 seconds**, defaulting to 8 when omitted |
| Veo 3 via Gemini Developer API | Audio-off variants are unsupported. Vertex support can differ; use only publicly listed variants |
| Omni | Omit `duration`; explicit values return 400. The provider determines the actual length, reported as `durationSeconds` on completion. Only `720p` and audio-on variants are currently supported |

Omni rejects `extra_body.google` options `negativePrompt`, `seed`, and `enhancePrompt` with 400. Omni `pricingVariant` supports only `16:9` and `9:16` aspect ratios.

## Request

```json
{
  "model": "everyais/veo-3-1-generate-001",
  "prompt": "a timelapse of a blooming flower",
  "duration": 8,
  "pricingVariant": "1080p-with-audio"
}
```

## Response (submitted)

```json
{
  "id": "cm...",
  "object": "video.generation.job",
  "created": 1709884800,
  "model": "everyais/veo-3-1-generate-001",
  "status": "processing"
}
```

---

## GET /v1/videos/generations/{id}

Poll job status and results. **Put the `id` from the POST response in this path.**

> ⚠️ You cannot look the job up through `/v1/outputs/{requestId}`. Video job ids and request ids live in
> separate spaces, so polling there always returns 404.

While a job is in progress the response carries a `Retry-After: 5` header — poll at 5-second intervals.

There are four `status` values.

| status | Meaning |
|--------|---------|
| `processing` | Submission, provider processing, or settlement in progress |
| `completed` | Done — includes `durationSeconds` and `data` |
| `failed` | Failed or timed out — includes `error` |
| `cancelled` | Cancelled |

```json
{
  "id": "cm...",
  "object": "video.generation.job",
  "created": 1709884800,
  "model": "everyais/veo-3-1-generate-001",
  "status": "completed",
  "durationSeconds": 8,
  "data": [{ "url": "https://..." }]
}
```

In rare cases where the outcome of the provider call could not be confirmed, `processing` comes back together with
`outcome_unknown: true`, plus `requires_manual_review: true` when an operator needs to check it.

If the job does not exist, has expired (24 hours), or belongs to a different API key, you get a 404 `job_not_found`.

## Billing

`total cost = durationSeconds × per-second price`. If you specify `pricingVariant`, that variant's unit price takes precedence.
For example, `everyais/veo-3-1-generate-001` offers the `720p-with-audio` · `1080p-with-audio` · `4k-with-audio`
variants. Check the exact keys and unit prices in the `pricing` field of the `GET /v1/models` response.

---

## GET /v1/models

_List models and retrieve a single model. Slugs containing slashes are supported._

Source: https://platform.everyais.com/en/docs/models
Updated: 2026-09-10T15:36:34.541Z

Returns the list of available models. If your API key has an allowed-model list configured, the response is filtered to that list.
Responses carry `Cache-Control: private, max-age=60`.

Capability booleans mean `true` = supported, `false` = unsupported; an omitted field means support is unverified. Distinguish `sampling`, `json_mode`, `json_mode_with_tools`, `web_search_with_tools`, `structured_outputs`, `parallel_tool_calls`, and `image_mask`. `limits.reasoning_efforts`, `limits.supported_sizes`, `limits.supported_qualities`, `limits.supported_durations`, and `limits.max_images` describe model-specific values. An empty list means there are no supported values. If a public model ID has several provider routes, metadata exposes only values guaranteed across them. Check each endpoint's documentation for combinations and generation/editing differences.

## Parameters by provider route

`GET /v1/models` returns `parameter_constraints` as `[{ provider, parameters }]`. `provider` is a normalized provider slug; `parameters` groups API parameter keys under `chat`, `image-generation`, `image-edit`, and `video`. Each constraint uses `supported`, `type`, `allowed_values`, `minimum`, and `maximum` for support, allowed values, and ranges. Example: `{"provider":"google-vertex","parameters":{"chat":{"temperature":{"supported":true,"type":"number","minimum":0,"maximum":2}}}}`.

Nested fields use dotted keys such as `response_format.type` and `extra_body.google.top_k`. Omitted means unverified, not unrestricted. Generation and editing constraints can differ. Use the intersection across routes; do not combine their allowed values into a union. Existing `capabilities` and `limits` retain common guarantees. Older API responses may omit `parameter_constraints` entirely.

The live model options in these docs and Playground use the same model metadata. Unverified models remain listed. Explicit unsupported parameters or invalid values are validated **before credit reservation** and return **400** with `error.code: "unsupported_parameter"` and the offending field in `error.param`. Recheck saved options when switching models.


## Request

```http
GET /v1/models
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "everyais/claude-opus-5",
      "aliases": ["claude-opus-5"],
      "object": "model",
      "owned_by": "everyais",
      "created": 1782008704,
      "registered_at": "2026-06-21",
      "released_at": "2026-06-21",
      "updated_at": "2026-08-27T04:30:00.000Z",
      "name": "Claude Opus 5",
      "description": "(model summary, currently Korean only)",
      "series": "claude",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "knowledge_cutoff": null,
      "price_search_per_query": null,
      "supply": "first_party",
      "training_use": "never",
      "category": "LLM",
      "type": "chat",
      "supported_endpoints": ["/v1/chat/completions"],
      "capabilities": {
        "streaming": true,
        "tool_use": true,
        "vision": true,
        "json_mode": true,
        "structured_outputs": false,
        "sampling": false,
        "parallel_tool_calls": true,
        "reasoning": true,
        "web_search": false
      },
      "limits": { "max_tokens": 8192, "context_window": 200000, "reasoning_efforts": ["none", "low", "medium", "high"] },
      "parameter_constraints": [{ "provider": "aws-bedrock", "parameters": { "chat": { "max_tokens": { "supported": true, "type": "integer", "minimum": 1, "maximum": 8192 }, "reasoning_effort": { "supported": true, "type": "string", "allowed_values": ["none", "low", "medium", "high"] } } } }],
      "pricing": {
        "unit": "per_1m_tokens",
        "is_free": false,
        "input_per_1m": 3.51,
        "output_per_1m": 17.55
      },
      "discount_percent": 10,
      "available": true
    }
  ]
}
```

`created` is an epoch value for OpenAI compatibility; `registered_at` (the date the model was registered with the gateway) and `released_at` (the model's release date) are separate fields.

`supply` tells you **where the model is served from** — `first_party` means clouds everyais
contracts directly, `community` means third-party supplier GPUs (your prompts are processed on
hardware everyais does not operate), and `mixed` means both are available. **Community supply is
off by default on every account**; enable it in dashboard settings. While it is off, community-only
models are hidden from your key's list. Chat, Messages, and Responses return 404 `model_not_found`
when no callable candidate remains.

`pricing.unit` is one of `per_1m_tokens`, `per_image`, or `per_second`. Video models also include variant unit prices as `{key, price}` entries in `pricing.variants[]`.

`pricing.is_free === true` means **customer input, output, and cache tokens are free**.
Web search is billed separately. Do not infer free pricing from a numeric price of 0;
an absent or false flag must not be displayed as free.
Public token prices use the input/output pair from the eligible endpoint with the lowest sum of input and output rates.
Standard and long-context tiers are selected independently; cache rates come from the same endpoint as the corresponding tier. Input and output minimums from different routes are not combined.
Media rates are compared within the same billing unit, and variant rates within the same `key` and `meta`. All displayed prices include display discounts and exclude markup.
The billed amount is calculated separately by applying the account rate at request time. A manually pinned model reference remains a billing basis; it does not fix the public lowest price.

`pricing.conditions` lists the consent required for the displayed lowest rates: `community_supply` means allowing community supply,
and `training_use` means allowing routes where providers train on prompts and responses.
Conditions needed by the selected standard tier, long-context tier, media rates, and variants are combined; the field is omitted when none are needed. Do not infer price conditions from the model-wide `supply` or `training_use` classification.
The public catalog labels these conditions; authenticated key catalogs select rates only from routes permitted by the account or organization.

`discount_percent` is the current public promotion available to all users. A model-specific promotion takes precedence over a global model promotion; the value is `null` when none applies.

## List price and shown discount (`pricing.list` / `pricing.discount_percent`)

`pricing.list` is the provider's published **list price** (before discount), populated only for
the keys that also appear above as `pricing.input_per_1m` etc. Both list and shown prices exclude markup.
The public catalog's `pricing` shows the lowest rates among eligible endpoints, never the billed amount. Models without a list price omit the
`pricing.list` field entirely.

`pricing.discount_percent` computes `(1 − shown/list) × 100` for each key in `pricing.list`, then
shows the minimum percentage **only when every comparable rate is discounted**. Undiscounted rates
count as 0%, so a cache-only discount does not become a model-wide discount. When only some rates
are discounted, `pricing.list` remains and `pricing.discount_percent` is omitted.
When no rate is discounted, both fields are omitted.

⚠️ This is a **different axis** from the top-level `discount_percent` (the everyais promotion
discount above). `pricing.discount_percent` is the shown rate's discount off the provider's list
price, while the top-level `discount_percent` is the currently active everyais promotion. The two
values are independent and can both be present at once.

```json
{
  "pricing": {
    "unit": "per_1m_tokens",
    "input_per_1m": 0.75,
    "output_per_1m": 3.75,
    "cache_read_per_1m": 0.075,
    "list": {
      "input_per_1m": 1.5,
      "output_per_1m": 7.5,
      "cache_read_per_1m": 0.15
    },
    "discount_percent": 50
  }
}
```

## Display metadata fields

| Field | Description |
|-------|-------------|
| `name` | Human-readable display name |
| `description` | Model summary. Currently written **in Korean only**; null when absent |
| `series` | Model family token (`claude`, `gemini`, `gpt`, …). null when unknown |
| `input_modalities` | Input modalities — `text`, `image` |
| `output_modalities` | Output modalities — `text`, `image`, `video` |
| `knowledge_cutoff` | Training knowledge cutoff as `YYYY-MM-DD`. Populated **only for models with an official vendor announcement**; null otherwise (we do not fill in estimates) |
| `price_search_per_query` | Reference cost per search billing unit (USD): an executed Google query or a search-enabled Z.AI request. null when unsupported or no public reference cost is available — never 0 |
| `available` | Whether the model is callable right now |
| `aliases` | Public inbound names that resolve to this id (last-segment, dotted versions, curated Cursor/OpenAI ids). Not extra catalog rows |

`capabilities.vision` is true whenever `input_modalities` contains `image`.
Use `capabilities.web_search` to determine support. `price_search_per_query` is numeric only
when a public reference cost is available, so it may be null while the capability is true.
The Claude model above accepts image input, so `vision` is true; it does not support web search.

---

## GET /v1/models/{model}

Retrieve a single model. Model ids contain slashes, so **append the id to the path as-is**.

```
GET /v1/models/everyais/gemini-3-5-flash
```

If the model does not exist or you do not have access to it, the endpoint returns 404 `model_not_found`.

## Training use and long-context pricing

`training_use` describes provider use of prompts and completions for training: `never`, `opt_in`,
`mixed` (both endpoint types), or `none` (no active endpoints).
This consent is separate from community supply and is off by default. Organization keys use organization consent.
Without consent, training-only models are filtered out. Chat, Messages, and Responses
return 404 `model_not_found` when no callable candidate remains.

When `pricing.long_context` is present, the higher tier applies when input tokens **exceed** `threshold_tokens`.
The base tier's lowest rates are the top-level `pricing.input_per_1m` / `pricing.output_per_1m`.
The long-context tier uses `pricing.long_context.input_per_1m` / `output_per_1m`;
`long_context.base_input_per_1m` / `base_output_per_1m` are **compatibility aliases for the long-context costs**.
Catalog prices are not a billing quote.
Use response cost headers and usage records for the amount billed under your account's rates.

---

## GET /v1/outputs/{requestId}

_Retrieve a stored request and refresh its output URLs, valid for 10 minutes._

Source: https://platform.everyais.com/en/docs/output-retrieval
Updated: 2026-09-08T10:12:16.657Z

Completed requests remain available for **24 hours**. Authenticate with an API key or user session; only requests accessible to that principal are returned.

Returns the details of a single request and the URLs of its result files. `urls` are presigned URLs valid for 10 minutes.

```json
{
  "id": "cm...",
  "model": "everyais/imagen-4-generate-001",
  "endpoint": "/v1/images/generations",
  "status": "COMPLETED",
  "inputTokens": 0,
  "outputTokens": 0,
  "imageCount": 1,
  "totalCost": 0.04,
  "latencyMs": 1200,
  "urls": ["https://..."],
  "createdAt": "2026-07-30T01:23:45.000Z"
}
```

Outputs outside your API key's scope return 403 `insufficient_scope`.

> ⚠️ Do not use this endpoint to poll video jobs.
> Poll videos with `GET /v1/videos/generations/{id}` (the id space is different).

---

# Guides

## Streaming

_Incremental tokens, SSE completion and errors, and final usage._

Source: https://platform.everyais.com/en/docs/streaming
Updated: 2026-09-08T10:12:19.139Z

## Chat streaming

Set up the environment variables from the [quickstart](./quickstart) and enable `stream: true`.
Use `stream_options.include_usage: true` to receive the final usage chunk.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EVERYAIS_API_KEY"],
    base_url="https://api.everyais.com/v1",
    timeout=240.0,
)
stream = client.chat.completions.create(
    model=os.environ["EVERYAIS_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
    stream_options={"include_usage": True},
)
try:
    for chunk in stream:
        if chunk.choices:
            print(chunk.choices[0].delta.content or "", end="", flush=True)
        if chunk.usage:
            print("\nUsage:", chunk.usage.total_tokens)
finally:
    stream.close()
```

## Reading SSE events

- Chat sends `data: {...}` frames and ends with `data: [DONE]`.
- The final usage chunk can have `choices: []`. Do not access `choices[0]` without checking.
- Comments such as `: ok` are connection heartbeats, not JSON.
- Network chunks are not SSE event boundaries. Custom consumers must buffer through a blank line and decode UTF-8 incrementally.

## Messages and Responses

| API | Completion and usage |
|-----|----------------------|
| `/v1/messages` | Anthropic events including `message_start`, `content_block_delta`, `message_delta`, and `message_stop` |
| `/v1/responses` | Responses events including `response.output_text.delta` and `response.completed` |

Use the corresponding SDK's stream consumer. Do not apply Chat's `[DONE]` handling to every format.
Responses with `background: true` return a job JSON object instead of a stream.

## Errors and disconnections

After HTTP 200 starts a stream, provider errors can still arrive inside events.
Treat error events, exceptions, or disconnection without a terminal event as failures.
Close the stream when cancelling and check generated output and billing before retrying.
`Idempotency-Key` cannot replay a completed SSE response.

Web-search citations arrive near the end. See [web search](./web-search) for final usage and citation handling.

---

## Prompt Caching

_Cache the repeated prefix to cut input cost — check the cost conditions before you turn it on._

Source: https://platform.everyais.com/en/docs/prompt-caching
Updated: 2026-08-23T01:49:02.315Z

Cache the **prefix that repeats on every request** — system prompts, tool definitions, prior turns — to reduce input cost.
Set the `everyais` option on the request (with the OpenAI SDK, pass it through `extra_body`).

```json
{
  "model": "everyais/claude-opus-5",
  "messages": [],
  "everyais": { "cache": "on", "cache_ttl": "5m" }
}
```

| Option | Behavior |
|------|------|
| `cache: "on"` | Attaches cache points automatically, in the order tool definitions → system → last user turn (up to 4) |
| `cache: "off"` | Removes both the automatic attachments and any `cache_control` the client sent itself |
| `cache_ttl: "5m" \| "1h"` | Cache lifetime. Default `5m`; `1h` has a higher write cost |
| Anthropic `/v1/messages` | `cache_control` breakpoints attached to blocks are passed through as-is |
| Gemini family | Implicit caching, so it hits with no extra configuration and there is no cache-write billing |

Cache read/write tokens are billed as separate line items at the provider's unit prices,
and you can confirm whether a hit actually occurred from `usage.prompt_tokens_details.cached_tokens` in the response.

## ⚠️ Check this before you turn it on — a cache write costs more than input

A cache hit (read) is billed at roughly 10% of the input unit price, but **a cache write costs more than the input unit price**
(about 1.25x for 5m, about 2x for 1h).

So if the prefix changes on every request, you incur the write cost over and over and it **ends up more expensive than leaving caching off**.
Turn it on only for multi-turn requests that continue a conversation with a fixed prefix; do not turn it on for one-off short requests.

---

## Async Jobs

_Responses background jobs, video generation polling, and the webhook alternative in one flow._

Source: https://platform.everyais.com/en/docs/async-jobs
Updated: 2026-09-08T10:12:17.948Z

Long-running work uses the **async job** model: you submit the request and collect the result later.
The gateway has two kinds, and their polling paths differ.

## 1. Responses background jobs

Pass `background: true` to `POST /v1/responses` and it responds immediately with `status: "queued"`.

```json
{
  "model": "everyais/claude-opus-5",
  "input": "A long research task...",
  "background": true
}
```

- Polling: `GET /v1/responses/{id}`
- State transitions: `queued` → `in_progress` → `completed` / `incomplete` / `failed` / `cancelled`
- Cancel: `POST /v1/responses/{id}/cancel` (only `queued` and `in_progress` can be cancelled, and the reserved credit is refunded)

## 2. Video generation jobs

`POST /v1/videos/generations` is always async. Poll with the `id` from the response.

- Polling: `GET /v1/videos/generations/{id}`
- While in progress you get `Retry-After: 5` — poll at 5-second intervals.
- Status: `processing` / `completed` / `failed` / `cancelled`

> ⚠️ Looking up a video job via `GET /v1/outputs/{requestId}` returns 404.
> Video job ids and completed request ids live in different spaces.

## 3. Webhooks instead of polling

To be notified on completion without polling, register a webhook endpoint in the dashboard and
subscribe to the `video.completed` and `video.failed` events.

The `video.completed` payload carries `jobId`, `model`, `status`, `durationSeconds`, `cost`, and `data`.

The other subscribable events are `credit.low`, `credit.depleted`, `credit.recharged`,
`credit.recharge_failed`, `cost.threshold`, `cost.limit_hit`, `payment.succeeded`,
`payment.failed`, `anomaly.detected`, and `key.expiring`.

---

## Imagen Model Notes

_Image count limits and the edit-only model in the Imagen family._

Source: https://platform.everyais.com/en/docs/imagen-notes
Updated: 2026-08-23T01:49:02.402Z

The Google Imagen family has different constraints per model. Before you use one, call `GET /v1/models` to confirm the model is currently in the catalog.

| Model | Notes |
|-------|-------|
| `everyais/imagen-4-ultra` | Only `n=1` is allowed (1 image limit) |
| `everyais/imagen-3-0-capability-001` | Edit-only — use it with `POST /v1/images/edits` for inpainting, outpainting, and background replacement |

Common constraints follow the endpoint docs — generation allows `n` up to 10, editing allows `n` up to 4.

---

## Web Search

_The model runs web searches — Google bills per search query; Z.AI bills per search-enabled request._

Source: https://platform.everyais.com/en/docs/web-search
Updated: 2026-09-09T05:24:39.181Z

When the model decides it needs to, it **runs a web search itself** and answers from the results.
Your client does not have to execute any tool — just add a single `web_search` entry to `tools`.

```json
{
  "model": "everyais/gemini-3-6-flash",
  "messages": [{"role": "user", "content": "What's the weather in Seoul today?"}],
  "tools": [{"type": "web_search"}]
}
```

```python
resp = client.chat.completions.create(
    model="everyais/gemini-3-6-flash",
    messages=[{"role": "user", "content": "What's the weather in Seoul today?"}],
    tools=[{"type": "web_search"}],
)
```

## Supported models

**Check `capabilities.web_search` in `GET /v1/models` — that list is the only source of truth.**
Support varies by model within both Gemini and Z.AI families. Check the current catalog.
Check this field for the example model too, and replace the ID if the supported models change.

```bash
curl https://api.everyais.com/v1/models \
  -H "Authorization: Bearer $EVERYAIS_API_KEY" \
  | jq '.data[] | select(.capabilities.web_search) | .id'
```

If you send `web_search` to a model that does not support it, you get 400
`web_search_unsupported_model` before the provider is called (no billing).

- You can put **at most 1** `web_search` entry in the `tools` array (2 or more returns 400).
- You can use it alongside function tools. `tool_choice: "none"` disables both functions and search. Requiring a tool or naming a function when only search is present returns 400.
- It is `/v1/chat/completions` only — `/v1/messages` and `/v1/responses` do not support it yet.

## Search billing by provider

**Google Gemini** bills per **executed search query**. Two queries within one request are billed as
two searches. If the model does not search, search billing is zero.

**Z.AI** bills **one search for each successful request with web search enabled**, even when there
are no results or the model does not search: `billed_queries = 1`. This search charge also applies
to models whose tokens are free.

- Search cost = `billed_queries × search price`, and it is **summed separately from** token billing.
- `pricing.is_free` covers only input, output, and cache tokens; it does not waive search charges.
- Content fetched by Google search is not billed as input tokens.
- Check the number of queries actually billed in `x_everyais.web_search.billed_queries` in the response.
  On non-streaming responses, the `x-everyais-cost-usd` header carries the total including search cost.

There is no parameter that forcibly caps the query count (the provider does not offer one).
To control spend, use the monthly/daily spend limit on the API key.

## Reading citations from the response

```json
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Seoul is clear today with a high of 28 degrees.",
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "url": "https://...",
            "title": "Seoul weather",
            "start_index": 0,
            "end_index": 47
          }
        }
      ]
    },
    "finish_reason": "stop"
  }],
  "x_everyais": {
    "web_search": {
      "queries": ["Seoul weather today"],
      "search_entry_point_html": "<div>...</div>",
      "billed_queries": 1
    }
  }
}
```

| Field | Description |
|------|------|
| `message.annotations[]` | OpenAI `url_citation`-compatible citations. `start_index`/`end_index` are **character indexes** into `content`, so slicing with them directly gives you the cited span |
| `x_everyais.web_search.queries` | The search terms the model actually ran |
| `x_everyais.web_search.billed_queries` | Search billing units: executed queries for Google; 1 per successful search-enabled Z.AI request |
| `x_everyais.web_search.search_entry_point_html` | Search suggestion HTML provided by Google |

> ⚠️ `search_entry_point_html` is HTML that Google **requires you to display**. If your service shows
> search results on screen, render it as-is. It is untrusted external HTML, so isolate it —
> for example with `<iframe sandbox srcdoc="...">`.

## Streaming

With `stream: true`, the citations and search info follow after the body.

1. The body `delta.content` chunks
2. One `delta.annotations` chunk (just before finish)
3. The `finish_reason` chunk
4. The usage chunk (`choices: []`) — this is where `x_everyais.web_search` rides

Citation indexes can only be fixed once the whole body has arrived, so they come exactly once, at the end.
The search query count is also only in the final usage chunk, so read the stream to the end to reconcile cost.

---

# Integrations

## Claude Code / Anthropic SDK

_anthropic-native integration via ANTHROPIC_BASE_URL._

Source: https://platform.everyais.com/en/docs/integration-claude-code
Updated: 2026-08-07T05:39:44.724Z

We provide an Anthropic Messages compatible `/v1/messages`, so anthropic-native tools work as-is.

```bash
export ANTHROPIC_BASE_URL=https://api.everyais.com
export ANTHROPIC_API_KEY=everyais_your_api_key
```

**Do not include** `/v1` in the base URL — the SDK appends `/v1/messages` itself.

Claude Code calls `POST /v1/messages/count_tokens` before a request.
This call is not billed and does not go out to the upstream provider.

---

## Cursor

_Connect by overriding the OpenAI Base URL._

Source: https://platform.everyais.com/en/docs/integration-cursor
Updated: 2026-08-22T12:51:39.619Z

1. In Settings → Models → API Keys, enter your everyais key as the **OpenAI API Key**.
2. Enable **Override OpenAI Base URL** and enter `https://api.everyais.com/v1`.
3. Do **not** add custom models for names Cursor already lists (for example Claude Opus 5, Gemini 3.5 Flash). The same key resolves public inbound ids (`claude-opus-5`, `gemini-3.5-flash`) to the canonical slug.
4. Only add a canonical `everyais/a/...` id and click Verify for catalog models that Cursor does not list.

Note: a custom key in Cursor applies only to chat models (Tab autocomplete uses Cursor's own model). Cursor may hide thinking text streamed from a custom API.

---

## opencode

_Example openai-compatible provider configuration._

Source: https://platform.everyais.com/en/docs/integration-opencode
Updated: 2026-08-23T01:49:02.216Z

Add a provider to `opencode.json`.

```json
{
  "provider": {
    "everyais": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.everyais.com/v1",
        "apiKey": "{env:EVERYAIS_API_KEY}"
      },
      "models": {
        "everyais/claude-opus-5": { "name": "Claude Opus 5" },
        "everyais/gemini-3-5-flash": { "name": "Gemini 3.5 Flash" }
      }
    }
  }
}
```

Look up the IDs to put in `models` with `GET /v1/models` or in the model catalog.

---

## Continue / Cline / Other OpenAI-Compatible Tools

_The shared pattern: provider=openai plus a base URL override._

Source: https://platform.everyais.com/en/docs/integration-openai-compatible-tools
Updated: 2026-08-23T01:49:02.265Z

Set the provider to `openai` and fill in the following values.

| Field | Value |
|------|-----|
| base URL | `https://api.everyais.com/v1` |
| API key | `everyais_...` |
| model | A model ID from the catalog (e.g. `everyais/gemini-3-5-flash`) |

Omitting the `everyais/` prefix from the model name still maps automatically, but it is safer to write the full ID in your tool configuration.

---

# Reference

## Error Format & Rate Limits

_OpenAI-compatible error envelope, status code table, rate limit headers._

Source: https://platform.everyais.com/en/docs/errors-and-rate-limits
Updated: 2026-09-08T10:12:19.697Z

Core inference APIs such as Chat use the OpenAI-compatible envelope below.
Messages may return Anthropic-shaped errors (`type: "error"`); errors after a stream starts arrive in SSE data.

```json
{
  "error": {
    "message": "Incorrect API key provided. ...",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

| Status | type / code | Meaning |
|------|-------------|------|
| 400 | `invalid_request_error` | Invalid parameter / context length exceeded (do not retry) |
| 401 | `authentication_error` / `missing_api_key` · `invalid_api_key` | Key missing, wrong, or expired |
| 402 | `insufficient_quota_error` / `insufficient_quota` · `spend_limit_exceeded` | Insufficient credit or spend limit reached |
| 403 | `permission_error` / `model_not_allowed` · `insufficient_scope` | Restricted by the key's allowed models or scopes |
| 404 | `invalid_request_error` / `model_not_found` · `job_not_found` | Model or job does not exist |
| 413 | `invalid_request_error` | Request body too large — see [body limits](./base-url) |
| 429 | `rate_limit_error` / `rate_limit_exceeded` | Rate limit — retry after the `Retry-After` header |
| 502 | `api_error` / `backend_unavailable` | Upstream provider failure (retryable) |

## Rate limits

The default rate limit is **100 req/min** per key, and you can adjust it when you create or edit the key.
Check your remaining quota with the `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` response headers.

Auth endpoints (login, signup, and so on) have a separate, lower limit.

## Retry decisions

- Resolve input, authentication, credits, or access-policy issues before retrying 400, 401, 402, or 403.
- For 429, wait the number of seconds in `Retry-After`. `X-RateLimit-Reset` is a Unix timestamp in milliseconds.
- A 502 or 503 may be temporary. Increase the delay between retries and check whether the operation already ran.
- 409 `idempotency_in_progress` means the same request is still processing. Wait rather than resubmitting with a new key.
- 409 `idempotency_key_reused` means a different body was sent with the same key.
- 409 `idempotency_response_not_replayable` means an accepted stream or large response cannot be replayed.

Log `x-request-id`, HTTP status, and `error.code` to help trace failures.
Video POSTs do not support `Idempotency-Key`; resubmitting after a lost response can create duplicate jobs.
See [idempotency scope](./compatibility-features) and [video polling](./videos-generations).

---

## Compatibility features

_Optional model name prefix, cost header, Idempotency-Key, per-endpoint limits._

Source: https://platform.everyais.com/en/docs/compatibility-features
Updated: 2026-09-08T10:12:20.149Z

## Optional model name prefix

Calls work without `everyais/`. When the last segment is unique in the catalog,
`claude-opus-5` resolves to `everyais/claude-opus-5`. Dotted names
(`gemini-3.5-flash`) and curated public ids (`gpt-5.4` → `everyais/openai-gpt-5-4`)
map only when that canonical is currently sold. Ambiguous names 404 instead of guessing.
Provider-native model IDs map through admin `ModelAlias`.
`GET /v1/models` lists these inbound names on each row as `aliases`.

## Per-call cost header

Non-streaming responses include the service price (USD) for that request in the `x-everyais-cost-usd` header.
Use it for agent budget guards.

## Idempotency-Key

Supported for Chat, Messages, Responses, and image generation/editing. **Video submission is excluded.**
Retry the identical body with the same `Idempotency-Key`, API key, route, and authorization policy.
Keys can be up to 255 characters; records are kept for 24 hours. Different JSON whitespace or field order counts as a different body.

- Successful JSON responses up to 300 KiB can be replayed with `Idempotent-Replayed: true`.
- Reusing a key with a different body, or while a request is in progress, returns 409.
- SSE and large successful responses are not replayed. A marker blocks duplicate execution; a repeat returns 409.
- Failed responses are not cached. Requests may proceed if the idempotency store is unavailable, so this is not an absolute exactly-once guarantee.

See [errors and retries](./errors-and-rate-limits) before enabling automatic retries.

## usage token details

When the provider reports them, `usage.prompt_tokens_details.cached_tokens` (cache hit) and
`cache_creation_tokens` (cache creation) are included.

## Per-key budget and scopes

In the dashboard you can set a monthly/daily/per-minute spend limit (USD) per API key and the allowed endpoint scopes
(`chat`, `images`, `video`, `models:read`).
Exceeding the limit returns 402, and a call outside the scopes returns 403 (leaving all scopes empty allows everything).

## Per-endpoint limits

| Item | Limit |
|------|------|
| `n` on `/v1/chat/completions` | **Only 1 is supported** — 2 or more returns 400 |
| `n` on `/v1/images/generations` | 1–10 |
| `n` on `/v1/images/edits` | 1–4 |


See [Base URL and request limits](./base-url) for time budgets and body sizes.
Dedicated `/v1/embeddings` and `/v1/audio/*` APIs are not available.

---