# 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 prices.

Updated: 2026-10-19T10:08:38.450Z

<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.

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

Browse the callable models and their reference prices on the public pages below.
- English: https://platform.everyais.com/en/models
- 한국어: https://platform.everyais.com/models
- `everyais/gemini-4-argon`
- `everyais/claude-haiku-5-5`
- `everyais/gemini-nano-banana-2-1`
- `everyais/gpt-6-1-sol`
- `everyais/grok-4-7`
- `everyais/claude-sonnet-5-5`
- `everyais/gpt-6-luna`
- `everyais/gpt-6-sol`
- `everyais/claude-opus-5-5`
- `everyais/gpt-6-astra`
- `everyais/gpt-image-2-5-sunburst`
- `everyais/gpt-image-2-5-flare`
- `everyais/gemini-3-8-flash`
- `everyais/claude-fable-5-1`
- `everyais/kimi-k3`
- `everyais/gemini-omni-1-1-flash`
- `everyais/nemotron-3-5-lightning`
- `everyais/gemini-omni-flash-preview`
- `everyais/gemini-3-1-flash-lite-image`
- `everyais/claude-fable-5`
- `everyais/minimax-m3`
- `everyais/gemini-3-1-flash-image`
- `everyais/deepseek-v4-pro-0813`
- `everyais/deepseek-v4-flash-0731`
- `everyais/gemini-3-1-pro-preview`
- `everyais/glm-5-3`
- `everyais/glm-5-3-flash`
- `everyais/gemini-3-pro-image`
- `everyais/veo-3-1-fast-generate-001`
- `everyais/veo-3-1-generate-001`
- `everyais/gemini-2-5-flash-image`
- `everyais/qwen-3.8-27b`
- `everyais/deepseek-v4-1-flash-1017`
- `everyais/muse-spark-open`
- `everyais/nemotron-3-5-super-vl`
- `everyais/flux-3-image-klein`
- `everyais/minimax-h3-turbo`

<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-10-13T08:20:31.119Z

## 1. Prepare an API key

[Create a key in the dashboard](https://platform.everyais.com/dashboard/keys) and [add credits](https://platform.everyais.com/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
export EVERYAIS_MODEL="everyais/gemini-3-5-flash-lite"
```

To use another model, copy its ID from the [model directory](https://platform.everyais.com/en/models) and replace the value.
Use `GET /v1/models` to list models your key can call, and see [model selection](https://platform.everyais.com/en/docs/model-selection) for capabilities and access policies.
If your key restricts scopes, it needs `models:read` for listing and `chat` for generation.

## 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 @- <<EOF
{
  "model": "$EVERYAIS_MODEL",
  "messages": [{"role": "user", "content": "Hello!"}]
}
EOF
```

### 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!"}],
)
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!" }],
});
console.log(response.choices[0].message.content);
```

## Next steps

| Goal | Documentation |
|------|---------------|
| Display tokens as they arrive | [Streaming](https://platform.everyais.com/en/docs/streaming) |
| Connect Claude Code or the Anthropic SDK | [Messages](https://platform.everyais.com/en/docs/messages) · [Integration](https://platform.everyais.com/en/docs/integration-claude-code) |
| Generate text asynchronously | [Responses](https://platform.everyais.com/en/docs/responses) |
| Generate or edit images | [Image generation](https://platform.everyais.com/en/docs/images-generations) · [Image editing](https://platform.everyais.com/en/docs/images-edits) |
| Generate video | [Video jobs](https://platform.everyais.com/en/docs/videos-generations) |
| Handle a failed request | [Errors and retries](https://platform.everyais.com/en/docs/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-10-13T08:20:25.570Z

## 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](https://platform.everyais.com/en/docs/streaming), [async jobs](https://platform.everyais.com/en/docs/async-jobs), and [retry decisions](https://platform.everyais.com/en/docs/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](https://platform.everyais.com/llms.txt),
and [full documentation](https://platform.everyais.com/llms-full.txt) are available without authentication.
Browse the [model directory](https://platform.everyais.com/en/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](https://platform.everyais.com/en/docs/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-10-16T06:17:55.266Z

## 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](https://platform.everyais.com/en/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.context_window` | Model-specific context window |
| `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.

### Parameter policy

Use the selected model’s `parameter_profile` for `required` inputs, omission `defaults`, manual `parameters`, and `combinations`. `GET /v1/models` also provides `capabilities` and `limits`.

| `everyais.parameter_policy` | Behavior |
|---|---|
| `auto` (default) | Omit unsupported sampling (`temperature`, `top_p`, penalties, `top_k`), `seed`, and `user`, and safely reduce values. Other unsupported options (`stop`, `logprobs`, tools, …) return **400** |
| `strict` | Reject explicit unsupported values or combinations with **400** `unsupported_parameter` |

Check `param`, `action`, `reason`, and `applied` in `x_everyais.parameter_warnings`. Unverified does not mean unlimited. Tools, masks, and response formats are not silently rewritten. `parameter_constraints` lists per-route support. Options available on only some routes also appear in `parameter_profile.routes`.

## 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.

See [model fields](https://platform.everyais.com/en/docs/models) for prices and access conditions.

---

# 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-10-16T06:17:42.570Z

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | Model ID (e.g. `everyais/gemini-3-5-flash-lite`) |
| `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). Send images (`image_url`) as base64 data URLs — Claude, GPT (Bedrock), and Gemini routes reject remote https URLs with **400**; only vLLM-based routes (Nebius, community supply) accept https URLs |
| `stream` | boolean | No | SSE streaming (default `false`) |
| `stream_options` | object | No | With `{"include_usage": true}`, the final chunk includes usage |
| `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. Some models (e.g. Claude Opus 5.5, Sonnet 5.5, Fable 5.1) reject forced use (`required` or a named function) with **400** — check `tool_choice` in the model's `parameter_profile` |
| `response_format` | object | No | `{"type":"text"}` · `{"type":"json_object"}` · `{"type":"json_schema","json_schema":{...}}` |
| `reasoning_effort` | string | No | Common `low` / `medium` / `high` / `xhigh` / `max`. Extra values such as `none` / `minimal` are published per model |
| `parallel_tool_calls` | boolean | No | Allow parallel tool calls |
| `logprobs` / `top_logprobs` | boolean / integer | No | Check the selected model options. `top_logprobs` is 0–20 |
| `verbosity` | string | No | `low` / `medium` / `high`. GPT routes only (OpenAI, Mantle, Bedrock); others return **400** |
| `prompt_cache_key` | string | No | OpenAI prompt-cache routing key (≤1024 characters). GPT routes only |
| `safety_identifier` | string | No | Hashed end-user ID for provider abuse detection (≤64 characters). GPT routes only |
| `logit_bias` | object | No | Token ID → -100–100, up to 300 entries. vLLM-based routes only (Nebius, community supply) |
| `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. Gemini takes `google.top_k` and `google.media_resolution` (`low`/`medium`/`high`, image/video input token resolution) |

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

Unknown schema fields (`store`, `service_tier`, and similar) return **400**. Public `allowed_values` are not the same as route-native `native_allowed_values`. An unverified output limit does not block approval, sale, or an explicit value; omission defaults are not a finalized policy. Unimplemented image size/quality and video duration values return **400**.

## Model options

Check the table above for the values the selected model supports (in the API: `capabilities`, `limits`, and `parameter_constraints` in `GET /v1/models`). Whether an unsupported value is adjusted or rejected with **400** is described under parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy).

Use strict schemas only with `structured_outputs: true`. Continue tool conversations with the same model and preserve the original `tool_calls`. Gemini needs `tool_calls[].extra_content.google.thought_signature`; OpenAI Responses needs `extra_content.openai.reasoning_id` and `reasoning_encrypted_content`.

## Request

```json
{
  "model": "everyais/gemini-3-5-flash-lite",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false
}
```

## Response

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709884800,
  "model": "everyais/gemini-3-5-flash-lite",
  "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](https://platform.everyais.com/en/docs/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-10-16T06:17:46.757Z

## 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) |
| `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 ≥ 1024) · `{"type":"adaptive"}` · `{"type":"disabled"}` |
| `output_config` | object | No | `effort` (`low`–`max`, with adaptive or omitted thinking) · `format` (`{"type":"json_schema","schema":{...}}`, structured-output models only) |
| `everyais` | object | No | Gateway caching options |

If you attach `cache_control` directly to a block, it is passed through as-is (see prompt caching). `document` and image `tool_result` blocks return **400**. `metadata.user_id` is forwarded as Anthropic metadata. Send image blocks with `source.type: "base64"` (a `url` source has the same limits as https URLs in Chat). Models that reject forced tool use (`any`, `tool`) are the same as in Chat.

To continue a tool conversation, send the response `content` blocks back unchanged, including `thinking` blocks — Gemini's tool signature travels in the `thinking` block `signature`. `stop_reason: "stop_sequence"` and `stop_sequence` are set only on routes where the provider reports the matched string (Claude, vLLM-based); Gemini and GPT return `end_turn` even when a `stop_sequences` entry stopped the output.

## Model options

Check the table above for the values the selected model supports (in the API: `capabilities`, `limits`, and `parameter_constraints` in `GET /v1/models`). Whether an unsupported value is adjusted or rejected with **400** is described under parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy).

For models supporting manual thinking, use `budget_tokens ≥ 1024`. Web search is available through Chat only.

## Request

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

## Response

```json
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "everyais/claude-sonnet-5-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 **token estimate** that may differ from actual usage.
- The request body takes the same shape as `/v1/messages`.

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

---

## POST /v1/responses

_Responses format, background jobs, and cancellation._

Source: https://platform.everyais.com/en/docs/responses
Updated: 2026-10-16T06:17:50.959Z

With the SDK use `extra_body={"reasoning_effort":"low","everyais":{"parameter_policy":"strict"}}`. Native `reasoning` objects and stateful fields such as `previous_response_id` return **400**. Flat function/`tool_choice` are rewritten to the nested Chat form, and `text.format` (OpenAI's flat `{"type":"json_schema","name","schema","strict"}` or the nested Chat form) becomes `response_format`. `store` is accepted only as `false`. To continue a tool conversation, send every response `output` item (including `reasoning`) back with the `function_call_output` — Gemini's tool signature travels in the `reasoning` item's `encrypted_content`.

## 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 |
| `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 | Common `low` / `medium` / `high` / `xhigh` / `max`. Extra values such as `none` / `minimal` are published per model |
| `text` | object | No | `format` (chat `response_format`) · `verbosity` (`low`/`medium`/`high`, GPT routes only) |
| `prompt_cache_key` / `safety_identifier` | string | No | GPT routes only; same meaning as in chat |
| `user` | string | No | End-user identifier |
| `everyais` | object | No | Gateway caching options |

## Model options

Check the table above for the values the selected model supports (in the API: `capabilities`, `limits`, and `parameter_constraints` in `GET /v1/models`). Whether an unsupported value is adjusted or rejected with **400** is described under parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy).

Omission uses the model's highest native effort (on manual thinking-budget models, the highest whose budget fits under your max tokens). A missing common level is executed as `high`. `none` disables reasoning only when the model publishes it as an extra value. Use Chat for web search, `response_format`, and `parallel_tool_calls`.

## Request

```json
{
  "model": "everyais/gemini-3-5-flash-lite",
  "input": "Hello!",
  "instructions": "Be concise."
}
```

## Response

```json
{
  "id": "resp_example",
  "object": "response",
  "created_at": 1709884800,
  "model": "everyais/gemini-3-5-flash-lite",
  "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,
  "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/gemini-3-5-flash-lite",
  "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-10-18T15:54:57.648Z

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | A model ID in the IMAGE category |
| `prompt` | string | Yes | 1–16,000 characters. A provider with a lower limit may reject longer prompts |
| `n` | integer | No | Number of images to generate, **1–10** (default 1) |
| `size` | string | No | Pixel `WxH` or `auto` (e.g. `256x256` · `512x512` · `1024x1024` · `1792x1024` · `1024x1792` · `1536x1024` · `1024x1536` · `auto`) or a resolution tier (same values as `resolution`). Pixels take precedence; a contradicting `aspect_ratio` or `resolution` returns **400** |
| `aspect_ratio` | string | No | `1:1` · `16:9` · `9:16` · `4:3` · `3:4` · `3:2` · `2:3` · `4:5` · `5:4` · `1:2` · `2:1` · `7:5` · `5:7` · `1:4` · `4:1` · `1:8` · `8:1` · `9:21` · `21:9` · `auto` (provider default). Per-model values: see aspect ratio and resolution below |
| `resolution` | string | No | `512` · `768` · `1K` · `1.5K` · `2K` · `4K`. 1K ≈ 1 MP, 2K ≈ 4 MP, 4K = the model's largest tier |
| `quality` | string | No | `standard` · `hd` · `low` · `medium` · `high` · `xhigh` · `max` · `auto` — see model-specific values and omission defaults below (`xhigh`/`max` on GPT Image 2.5) |
| `response_format` | string | No | `url` (default) · `b64_json` |
| `output_format` | string | No | `png` · `jpeg` · `webp`. Only models listing `output_format` in `parameter_profile` accept it; others return **400** |
| `output_compression` | integer | No | 0–100, for `jpeg`/`webp` output only (GPT Image) |
| `background` | string | No | `transparent` · `opaque` · `auto` (GPT Image). Transparent requires `png` or `webp` output |
| `moderation` | string | No | `low` · `auto` (GPT Image) |
| `user` | string | No | End-user identifier |
| `extra_body.google` | object | No | **deprecated** — `aspect_ratio` and `image_size` are aliases of `aspect_ratio` and `resolution` above. A differing value returns **400** |
| `extra_body.gpunode` | object | No | Managed GPU node image models only: `seed` (same value, same result; image i of n uses seed+i) · `num_inference_steps` |
| `prompt_upsampling` | boolean | No | FLUX 3 Image Klein only: prompt upsampler on/off (default `true`). Other models return **400** |

## Aspect ratio and resolution

Each model publishes its supported values in `aspect_ratio` and `resolution` under `parameter_profile.tasks["image-generation"].parameters` (the Playground uses the same values). The default `auto` policy moves an unsupported ratio to the nearest supported one and a resolution to the nearest supported tier at or below the request (else the smallest), reporting each change in `x_everyais.parameter_warnings`. `strict` returns **400**.

| Model | Wire mapping |
|---|---|
| Gemini image | `imageConfig` aspect ratio and size. A pixel `size` maps to the nearest ratio and tier (`3840x2160` → `16:9`, `4K`) |
| GPT Image 2.5 | Converted to a 16px-grid `WxH` — 1K ≈ 1 MP (16:9 `1360x768`), 2K ≈ 4 MP (`2720x1536`), 4K = the pixel budget (`3840x2160`) |
| Listed-size models (FLUX 3 Image Klein and others) | Picks from the published size list by ratio, then resolution. Size-specific pricing (`pricing.variants[].meta.sizes`) follows the chosen size |

Check the selected model's `n` limit and allowed sizes (`limits.supported_sizes`). GPT Image 2.5 accepts arbitrary `WIDTHxHEIGHT` (multiples of 16, edges ≤3840, ratio 1:3–3:1, 655,360–8,294,400 pixels). Token-priced image models bill more output tokens for larger sizes and higher quality. When a size is priced differently, it appears in `meta.sizes` of a `pricing.variants[]` entry.
For the image models you can use, check `GET /v1/models` for entries whose `category` is `IMAGE`.

## FLUX 3 Image Klein (`everyais/flux-3-image-klein`)

Black Forest Labs' FLUX 3 Image Klein (5.6B open weights, Qwen3-VL-4B text encoder).

| Item | Value |
|---|---|
| `prompt` | Up to 16,000 characters (all image endpoints) |
| `n` | 1–4 |
| Size | One of the 60 sizes below (`size`), or `aspect_ratio` + `resolution`. Default `1:1` · `1K` (1024x1024) |
| `output_format` | `png` · `jpeg` · `webp` (engine default `jpeg`) |
| `extra_body.gpunode.seed` | 0–2147483647 |
| `extra_body.gpunode.num_inference_steps` | 1–16 (default 16) |
| `prompt_upsampling` | boolean, default `true` — BFL's prompt upsampler rewrites the prompt into a full caption before generation, same as BFL's own API (same parameter name). Set `false` to send the prompt as typed. `extra_body.gpunode.prompt_upsampling` is the same switch (give one, or the same value in both) |
| `guidance_scale` · `negative_prompt` | Not supported — **400** |

When upsampling ran, each response item carries the upsampled caption as `revised_prompt`.

### Supported sizes (15 aspect ratios × 4 resolutions)

Resolutions `768` · `1K` · `1.5K` · `2K` (BFL calls them 768sq/1k/1.5k/2k). Pixel size is round16(E·√r) × round16(E/√r), with E = 768/1024/1536/2048 and r = width ÷ height. An explicit `size` must be one of these 60 values. BFL's `4k` tier is not offered: on this node (one 96 GB GPU) a single 4K image took over two minutes and some aspect ratios ran out of memory. `resolution: "4K"` snaps to `2K` under `auto` and returns **400** under `strict`. The default `auto` policy snaps to the nearest listed size and reports it in `x_everyais.parameter_warnings`; `strict` returns **400**.

| Aspect ratio | `768` | `1K` | `1.5K` | `2K` |
|---|---|---|---|---|
| `21:9` | 1168x496 | 1568x672 | 2352x1008 | 3136x1344 |
| `2:1` | 1088x544 | 1456x720 | 2176x1088 | 2896x1456 |
| `16:9` | 1024x576 | 1360x768 | 2048x1152 | 2736x1536 |
| `3:2` | 944x624 | 1248x832 | 1888x1248 | 2512x1680 |
| `7:5` | 912x656 | 1216x864 | 1824x1296 | 2416x1728 |
| `4:3` | 880x672 | 1184x880 | 1776x1328 | 2368x1776 |
| `5:4` | 864x688 | 1152x912 | 1712x1376 | 2288x1824 |
| `1:1` | 768x768 | 1024x1024 | 1536x1536 | 2048x2048 |
| `4:5` | 688x864 | 912x1152 | 1376x1712 | 1824x2288 |
| `3:4` | 672x880 | 880x1184 | 1328x1776 | 1776x2368 |
| `5:7` | 656x912 | 864x1216 | 1296x1824 | 1728x2416 |
| `2:3` | 624x944 | 832x1248 | 1248x1888 | 1680x2512 |
| `9:16` | 576x1024 | 768x1360 | 1152x2048 | 1536x2736 |
| `1:2` | 544x1088 | 720x1456 | 1088x2176 | 1456x2896 |
| `9:21` | 496x1168 | 672x1568 | 1008x2352 | 1344x3136 |

### Pricing (per image, USD)

| Output tier | Price |
|---|---|
| `768` | $0.008 |
| `1K` | $0.009 |
| `1.5K` | $0.011 |
| `2K` | $0.014 |

Generation and editing cost the same, multiplied by `n`. Actual billing follows your account rates.

### Bounding-box layout

Append a JSON list to the end of the prompt to control placement. Each element is `{"id","bbox":[top,left,bottom,right],"desc"}` on a 0–1000 grid. Refer to the element in the caption as `<id>`.

```json
{
  "model": "everyais/flux-3-image-klein",
  "prompt": "A cozy cafe window scene: a <cat> sleeps on the left windowsill and a <plant> stands on the right. [{\"id\":\"cat\",\"bbox\":[500,50,900,450],\"desc\":\"orange tabby cat curled up\"},{\"id\":\"plant\",\"bbox\":[300,600,900,900],\"desc\":\"potted monstera\"}]",
  "aspect_ratio": "3:2",
  "resolution": "1K",
  "extra_body": { "gpunode": { "seed": 42 } }
}
```

### Tips

- Full scene captions beat short prompts.
- There are no negative prompts — describe what should be there.
- Put text to render in quotes.
- Latency depends on size, reference count and the upsampler. Measured 2026-10-16 (GPU time, excluding queue and transfer): with the upsampler on, 768 ≈ 5 s, 1K 6–8 s, 1.5K ≈ 9 s, 2K ≈ 16 s, 2–3 reference edits 12–15 s, 10 reference edits ≈ 55 s. With it off, 1K ≈ 2 s. One node renders one image at a time, so bursts add queue time (no fixed SLA).
- License: FLUX Kommunity License (non-commercial, plus commercial use of outputs for qualifying users). Outputs pass a content (NSFW) filter and are AI-generated.

## Model options

Check the table above for the values the selected model supports (in the API: `capabilities`, `limits`, and `parameter_constraints` in `GET /v1/models`). Whether an unsupported value is adjusted or rejected with **400** is described under parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy).

Omitting size, aspect ratio, resolution, or quality applies the `defaults` in `parameter_profile`. For quality, check `limits.supported_qualities`.

## Request

```json
{
  "model": "<IMAGE model ID from GET /v1/models>",
  "prompt": "a beautiful sunset over mountains",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

## 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.
The `requestId` is the value of this response's `x-request-id` header (`x-everyais-operation-id` carries the same value). It is not in the response body, so store the header.

---

## 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-10-18T15:55:02.057Z

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | ID of a model that supports editing |
| `prompt` | string | Yes | 1–16,000 characters. A provider with a lower limit may reject longer prompts |
| `image` | string \| file \| array | Yes | Source image — a base64 string in JSON, a file part in multipart. FLUX 3 Image Klein accepts an array of 1–10 reference images |
| `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 | Pixel `WxH` or `auto` (e.g. `256x256` · `512x512` · `1024x1024` · `1792x1024` · `1024x1792` · `1536x1024` · `1024x1536` · `auto`) or a resolution tier. Same rules as generation; omission keeps the provider default (usually the input image's ratio) |
| `aspect_ratio` | string | No | `1:1` · `16:9` · `9:16` · `4:3` · `3:4` · `3:2` · `2:3` · `4:5` · `5:4` · `1:2` · `2:1` · `7:5` · `5:7` · `1:4` · `4:1` · `1:8` · `8:1` · `9:21` · `21:9` · `auto`. Changes the output ratio only when given |
| `resolution` | string | No | `512` · `768` · `1K` · `1.5K` · `2K` · `4K` |
| `response_format` | string | No | `url` (default) · `b64_json` |
| `quality` / `output_format` / `output_compression` / `background` | | No | Same meaning as generation (`/v1/images/generations`); supported models only |
| `extra_body.google` | object | No | **deprecated** — `aspect_ratio` and `image_size` alias `aspect_ratio` and `resolution`. A JSON string in multipart |
| `extra_body.gpunode` | object | No | Managed GPU node models only: `seed` · `num_inference_steps` · `prompt_upsampling` (FLUX 3 Image Klein). A JSON string in multipart |
| `prompt_upsampling` | boolean | No | FLUX 3 Image Klein only, same as generation. `true`/`false` in multipart |
| `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 options

Check the table above for the values the selected model supports (in the API: `capabilities`, `limits`, and `parameter_constraints` in `GET /v1/models`). Whether an unsupported value is adjusted or rejected with **400** is described under parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy).

Use a mask only with `capabilities.image_mask: true`. Supported aspect ratios, resolutions, and adjustment rules match [image generation](https://platform.everyais.com/en/docs/images-generations#doc-aspect-ratio-and-resolution). When size, aspect ratio, and resolution are all omitted, the edit keeps the provider default (usually the input image's ratio).

## 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://..." }
  ]
}
```

## FLUX 3 Image Klein editing (`everyais/flux-3-image-klein`)

- `image` is one image or an **array of 1–10 reference images**. In JSON use base64/data URLs; in multipart repeat `image` or `image[]` parts. JPEG, PNG, WebP. Body limits are unchanged (4 MiB multipart / 5 MiB JSON), so compress references before sending.
- `n`, `output_format`, `prompt_upsampling`, and `extra_body.gpunode` (`seed`, `num_inference_steps`) match generation (in multipart, `prompt_upsampling` is `true`/`false` and `extra_body` is a JSON string). Pricing also matches generation, by output tier (`768` $0.008 · `1K` $0.009 · `1.5K` $0.011 · `2K` $0.014, times `n`).
- Omitting `size`: the output follows the first reference. With one reference, same aspect ratio fitted to ≤4 MP and ≤4096 px per side; with several, the first reference is scaled under 1 MP on multiples of 16. Billing uses the nearest tier. If given, `size` must be one of the 60 sizes in [image generation](https://platform.everyais.com/en/docs/images-generations#doc-flux-3-image-klein).
- Refer to references in the prompt by position ("the first image", `<ref_image_0>` in box edits). This model has no mask.
- Describe the edit as the full target image. For box edits, append a JSON list to the prompt: `{"id","from":"ref_image_0"|null,"src_bbox","tgt_bbox","desc"}` (0–1000 grid; `tgt_bbox: null` removes). Boxes guide placement and scale; they are not hard masks.

```json
{
  "model": "everyais/flux-3-image-klein",
  "prompt": "Move the <mug> from the first image to the right side of the table. [{\"id\":\"mug\",\"from\":\"ref_image_0\",\"src_bbox\":[600,100,800,250],\"tgt_bbox\":[600,650,800,800],\"desc\":\"white ceramic mug\"}]",
  "image": ["<base64-encoded-image>"],
  "n": 1
}
```

---

## 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-10-18T15:55:06.267Z

## 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; Gemini Omni 1.1 takes 3–10) |
| `image` | string | No | First frame (image-to-video). JPEG/PNG/WebP data URL or base64; request body up to 5 MiB (Veo: JPEG/PNG only). Only models listing `image` in `parameter_constraints` accept it (Veo, Omni, managed GPU node models); others return **400** |
| `last_image` | string | No | Last frame, same format as `image`; both images together must fit the 5 MiB request body. With `image` it conditions first→last frames; alone it fixes only the last frame (Veo and Omni require `image`). Only models listing `last_image` in `parameter_constraints` accept it |
| `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 | `aspectRatio` (`16:9`/`9:16`, Veo and Omni) · Veo-only `negativePrompt` (≤4000 characters) · `seed` · `enhancePrompt` |
| `extra_body.gpunode` | object | No | Managed GPU node video models only: `size` (`WxH`, one of the model's published sizes) · `seed` · `num_inference_steps` |

## Model options

Check the table above for the values the selected model supports (in the API: `capabilities`, `limits`, and `parameter_constraints` in `GET /v1/models`). Whether an unsupported value is adjusted or rejected with **400** is described under parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy).

Check `limits.supported_durations` and `pricing.variants`. Omit them to use model defaults. Duration and resolution must form a supported combination.

## 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-10-18T17:35:54.106Z

## Request

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

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "everyais/claude-sonnet-5-5",
      "aliases": ["claude-sonnet-5-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 Sonnet 5.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", "/v1/messages", "/v1/responses"],
      "capabilities": {
        "streaming": true,
        "tool_use": true,
        "vision": true,
        "json_mode": true,
        "structured_outputs": true,
        "sampling": false,
        "parallel_tool_calls": true,
        "reasoning": true,
        "web_search": false
      },
      "limits": { "context_window": 1000000, "reasoning_efforts": ["low", "medium", "high", "xhigh", "max", "none"] },
      "parameter_profile": { "version": 1, "scope": "all-active-routes", "tasks": { "chat": { "status": "supported", "required": ["model", "messages"], "defaults": {}, "parameters": { "reasoning_effort": { "status": "supported", "type": "string", "allowed_values": ["low", "medium", "high", "xhigh", "max", "none"] } }, "combinations": [] } } },
      "parameter_constraints": [{ "provider": "aws-bedrock", "parameters": { "chat": { "reasoning_effort": { "supported": true, "type": "string", "allowed_values": ["low", "medium", "high", "xhigh", "max", "none"] } } } }],
      "pricing": {
        "unit": "per_1m_tokens",
        "is_free": false,
        "input_per_1m": 3.159,
        "output_per_1m": 15.795,
        "list": { "input_per_1m": 3.51, "output_per_1m": 17.55 },
        "discount_percent": 10
      },
      "discount_percent": 10,
      "available": true
    }
  ]
}
```

## Model fields

| Field | Description |
|-------|-------------|
| `id` · `aliases` | Model ID and accepted aliases |
| `name` · `description` · `series` | Display name, description, family |
| `category` | `LLM` · `IMAGE` · `VIDEO` |
| `supported_endpoints` | API paths |
| `available` | Current availability |
| `input_modalities` · `output_modalities` | Input and output formats |
| `created` · `registered_at` · `released_at` | Compatibility epoch, registration date, release date |
| `knowledge_cutoff` | Verified knowledge cutoff; null if unknown |
| `capabilities` | `true`: supported; `false`: unsupported; omitted: unverified |
| `limits` | Supported values and limits |
| `parameter_profile.tasks` | Required inputs, defaults, supported ranges, and combinations per operation |

`capabilities` distinguishes `sampling`, `json_mode`, `structured_outputs`, `json_mode_with_tools`, `web_search_with_tools`, `parallel_tool_calls`, and `image_mask`.
`limits` includes `reasoning_efforts`, `supported_sizes`, `supported_qualities`, `supported_durations`, and `max_images`. An empty array means no supported values.
Unsupported values or combinations return **400** `unsupported_parameter`; check `error.param` for the field. See parameter policy in [model selection and access](https://platform.everyais.com/en/docs/model-selection#doc-parameter-policy) for how values are adjusted.

## Pricing and access

| Field | Description |
|-------|-------------|
| `pricing` | Display rates. Actual costs apply account rates; check cost headers and usage |
| `pricing.is_free === true` | Free input, output, and cache tokens. Web search is billed separately |
| `pricing.list` · `pricing.discount_percent` | Prices before discounts and the minimum discount shared by all rates. Includes list-price discounts and all-customer promotions |
| `discount_percent` | The everyais promotional part of that discount (already reflected in the `pricing` rates). The maximum when the discount differs by provider route |
| `pricing.variants` | Variant `key` and `price` |
| `pricing.long_context` | Rates when input exceeds `threshold_tokens`. `base_input_per_1m` and `base_output_per_1m` are aliases for long-context rates |
| `price_search_per_query` | Base rate per search billing unit. Check `capabilities.web_search` for support |
| `pricing.conditions` | Required `community_supply` or `training_use` consent for shown rates |
| `supply` · `training_use` | Community supply and training-use conditions. Off by default; organization keys use organization settings |

Models requiring consent are excluded according to account settings.

## GET /v1/models/{model}

Append the full model ID, including its slashes.

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

Missing or inaccessible models return 404 `model_not_found`.

---

## 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-10-13T08:22:29.628Z

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

## Find the requestId

The `requestId` is the value of the `x-request-id` header on an image generation or edit response; `x-everyais-operation-id` carries the same value.
An `x-request-id` you send yourself is only a trace hint and does not become the stored id.
The response body does not include it, so store the response header if you plan to retrieve the result again.

```http
HTTP/1.1 200 OK
content-type: application/json
x-request-id: V1StGXR8_Z5jdHi6B-myT
x-everyais-operation-id: V1StGXR8_Z5jdHi6B-myT
```

## Retrieve the result

```http
GET /v1/outputs/V1StGXR8_Z5jdHi6B-myT
```

Returns the details of a single request and the URLs of its result files. `id` is the `requestId` you requested, and `urls` are presigned URLs valid for 10 minutes.

```json
{
  "id": "V1StGXR8_Z5jdHi6B-myT",
  "model": "everyais/gemini-3-1-flash-image",
  "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](https://platform.everyais.com/en/docs/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](https://platform.everyais.com/en/docs/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-10-13T08:22:51.433Z

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-sonnet-5-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 and video generation polling in one flow._

Source: https://platform.everyais.com/en/docs/async-jobs
Updated: 2026-10-13T08:22:55.628Z

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/gemini-3-5-flash-lite",
  "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.

---

## 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-10-13T08:22:59.824Z

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-5-flash-lite",
  "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-5-flash-lite",
    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 GLM 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

**Gemini models** 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.

**GLM models** 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-09-15T04:36:44.100Z

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.

---

## Cursor

_Connect by overriding the OpenAI Base URL._

Source: https://platform.everyais.com/en/docs/integration-cursor
Updated: 2026-10-13T08:22:38.854Z

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. The same key resolves public inbound ids (for example `claude-sonnet-5-5` and `gemini-3.5-flash-lite`) to the canonical slug.
4. Only for catalog models that Cursor does not list, add an id in the `everyais/<model>` form and click Verify.

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-10-13T08:22:43.044Z

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/gemini-3-5-flash-lite": { "name": "Gemini 3.5 Flash Lite" },
        "everyais/claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" }
      }
    }
  }
}
```

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

---

## Continue, Cline, and 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-10-13T08:22:47.238Z

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-lite`) |

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-10-13T08:23:09.262Z

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](https://platform.everyais.com/en/docs/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) |
| 503 | `api_error` / `model_warming` | A sleeping supply GPU is being started — retry after `Retry-After` seconds |

## 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.
- 503 `model_warming` means a GPU that was stopped for lack of requests is starting again. The request did not run; send the same request again after `Retry-After` seconds. Warm-up can take 10–20 minutes depending on the model.
- 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](https://platform.everyais.com/en/docs/compatibility-features) and [video polling](https://platform.everyais.com/en/docs/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-10-13T08:23:13.452Z

## Optional model name prefix

Calls work without `everyais/`. When the last segment is unique in the catalog,
`claude-sonnet-5-5` resolves to `everyais/claude-sonnet-5-5`. Dotted names
(`gemini-3.5-flash-lite` → `everyais/gemini-3-5-flash-lite`) and curated public ids that link a provider's model name to an everyais model
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](https://platform.everyais.com/en/docs/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](https://platform.everyais.com/en/docs/base-url) for time budgets and body sizes.
Dedicated `/v1/embeddings` and `/v1/audio/*` APIs are not available.

---