# Документация Elysium AI

Практическое руководство: от первого API-ключа до рабочего запроса, контроля расходов и обработки ошибок.

https://elysiumai.garden/docs

## Как проходит запрос

Ваше приложение обращается к одному API-адресу. Elysium AI проверяет ключ и баланс, отправляет запрос выбранной модели и возвращает ответ в OpenAI-совместимом формате.

1. Ваше приложение
2. Проверка ключа
3. Выбранная модель
4. Готовый ответ

```
POST /v1/chat/completions
Authorization: Bearer sk-...
Content-Type: application/json

{
  "model": "your-model-id",
  "messages": [
    {"role": "user", "content": "Привет!"}
  ]
}
```

```
HTTP/1.1 200 OK
Content-Type: application/json

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Привет! Чем помочь?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 7,
    "total_tokens": 16
  }
}
```

## Что понадобится

- Аккаунт с положительным балансом.
- API-ключ из личного кабинета.
- ID модели из каталога или GET /v1/models.
- ElysiumAI Gateaway: https://elysiumai.garden/v1.
- ElysiumAI RU Gateaway: https://ru.elysiumai.garden/v1.

- [Быстрый старт](https://elysiumai.garden/docs/quickstart): Первый запрос через curl, Python или JavaScript.
- [Авторизация](https://elysiumai.garden/docs/authentication): Как безопасно передавать и хранить API-ключ.
- [Модели](https://elysiumai.garden/docs/models): Как получить актуальные ID и выбрать подходящий endpoint.
- [Баланс и стоимость](https://elysiumai.garden/docs/billing): Как считаются списания и где смотреть расходы.
- [Кэш контекста](https://elysiumai.garden/docs/cache): Наглядный расчёт cache read и cache write.
- [Интеграции](https://elysiumai.garden/docs/integrations/overview): Подключение SDK, агентов и готовых приложений.

## Главный адрес

ElysiumAI Gateaway подходит для большинства клиентов. ElysiumAI RU Gateaway использует тот же API-ключ, модели, баланс и формат запросов через отдельный маршрут в РФ.

### ElysiumAI Gateaway

```text
https://elysiumai.garden/v1
```

### ElysiumAI RU Gateaway

```text
https://ru.elysiumai.garden/v1
```

> Оба адреса OpenAI-совместимы. Если один маршрут недоступен из вашей сети, переключите только Base URL — API-ключ и model ID менять не нужно.

---

# Быстрый старт

Создайте ключ, выберите модель и получите первый ответ.

https://elysiumai.garden/docs/quickstart

## 1. Создайте API-ключ

Откройте раздел API-ключей в кабинете и создайте новый ключ. Скопируйте его сразу после создания и храните только на сервере или в переменной окружения.

- [Открыть API-ключи](https://elysiumai.garden/dashboard/api-keys): Создание, отключение и индивидуальный бюджет ключа.

## 2. Получите ID модели

Используйте публичный каталог или запросите список моделей через API. Передавайте полученный ID без изменений в поле model.

### curl

```bash
curl https://elysiumai.garden/v1/models   -H "Authorization: Bearer $ELYSIUM_API_KEY"
```

## 3. Отправьте запрос

### curl

```bash
curl https://elysiumai.garden/v1/chat/completions   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"your-model-id","messages":[{"role":"user","content":"Привет!"}]}'
```

### Python

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ELYSIUM_API_KEY"],
    base_url="https://elysiumai.garden/v1",
)

response = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Привет!"}],
)

print(response.choices[0].message.content)
```

### JavaScript

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ELYSIUM_API_KEY,
  baseURL: "https://elysiumai.garden/v1",
});

const response = await client.chat.completions.create({
  model: "your-model-id",
  messages: [{ role: "user", content: "Привет!" }],
});

console.log(response.choices[0].message.content);
```

## 4. Прочитайте результат

Текст ответа находится в choices[0].message.content. Причина завершения — в finish_reason, а количество использованных токенов — в объекте usage.

1. JSON-запрос
2. Авторизация
3. Генерация
4. choices + usage

```
POST /v1/chat/completions
Authorization: Bearer sk-...
Content-Type: application/json

{
  "model": "your-model-id",
  "messages": [
    {"role": "user", "content": "Привет!"}
  ]
}
```

```
HTTP/1.1 200 OK
Content-Type: application/json

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Привет! Чем помочь?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 7,
    "total_tokens": 16
  }
}
```

---

# Авторизация и API-ключи

Как передавать ключ, ограничивать расходы и не раскрывать секрет приложению пользователя.

https://elysiumai.garden/docs/authentication

## Заголовок Authorization

Передавайте ключ в каждом API-запросе как Bearer token.

### HTTP header

```http
Authorization: Bearer sk-...
```

## Безопасное хранение

- Храните ключ в переменной окружения или менеджере секретов.
- Не добавляйте ключ в Git и клиентский JavaScript.
- Создавайте отдельный ключ для каждого приложения.
- Отключите ключ в кабинете сразу после возможной утечки.

> Запросы, выполненные с вашим ключом, считаются запросами вашего аккаунта. Используйте индивидуальный бюджет ключа, чтобы ограничить возможные расходы.

## Бюджет ключа

Для отдельного ключа можно включить максимальную сумму расходов. Когда лимит исчерпан, запросы этого ключа перестают выполняться, а остальные ключи аккаунта продолжают работать.

---

# Модели

Где брать актуальный model ID и как понять назначение модели.

https://elysiumai.garden/docs/models

## Актуальный список

Используйте каталог на сайте или GET /v1/models. Не копируйте ID из документации стороннего сервиса: название в каталоге Elysium AI может отличаться.

### GET /v1/models

```bash
curl https://elysiumai.garden/v1/models   -H "Authorization: Bearer $ELYSIUM_API_KEY"
```

## Как выбрать

| Задача | Что искать в каталоге |
| --- | --- |
| Диалог и генерация текста | Chat-модель |
| Поиск и RAG | Embedding-модель |
| Создание изображений | Image-модель |
| Распознавание аудио | Audio transcription |

> Карточка модели показывает доступные форматы и актуальные цены. Если формат не указан, не рассчитывайте на его поддержку.

## Уровни рассуждений

У моделей с поддержкой reasoning передавайте reasoning_effort только из списка на карточке модели. Каталог показывает реальные режимы модели, а совместимые значения клиентов шлюз при необходимости преобразует в ближайший режим.

| Семейство | Доступные значения reasoning_effort | Особенность |
| --- | --- | --- |
| GLM 5.x | high, max | По умолчанию max; отключение через enable_thinking=false |
| DeepSeek V4 | high, max | Два реальных уровня upstream |
| Kimi K3 | low, high, max | По умолчанию max |
| Qwen 3.6/3.7 | none, high | Шлюз преобразует их в enable_thinking=false/true |

> Automatic в LibreChat означает, что reasoning_effort не отправляется и действует значение модели или провайдера по умолчанию.

---

# Баланс и стоимость

Как формируется списание, где смотреть usage и как запросить остаток через API.

https://elysiumai.garden/docs/billing

## Из чего складывается цена

Для текстового запроса отдельно учитываются входные и выходные токены. Если модель возвращает данные о кэш-токенах, они рассчитываются по ценам cache read и cache write из каталога.

| Часть usage | Что означает |
| --- | --- |
| prompt_tokens | Полный вход в OpenAI-формате; может уже включать cache-токены |
| input_tokens | Обычный вход без cache в Anthropic-формате |
| completion_tokens | Сгенерированный ответ |
| cache_read_tokens | Токены, прочитанные из кэша |
| cache_write_tokens | Токены, записанные в кэш |

[Из чего складывается цена](https://elysiumai.garden/docs/billing#calculation)

## Проверка баланса через API

### Запрос

```bash
curl https://elysiumai.garden/v1/balance   -H "Authorization: Bearer $ELYSIUM_API_KEY"
```

### Ответ

```json
{
  "balance": 12.45,
  "total_spent": 7.55
}
```

> Баланс указывается в долларах. Для истории списаний используйте вкладку Analytics в личном кабинете.

## Где смотреть расход

- В ответе API — объект usage с количеством токенов.
- В кабинете — стоимость и история запросов.
- У каждого запроса есть request ID, который помогает найти точную запись в логах.

---

# NovelAI V4.5 и V5

Выбор точной модели, text-to-image и img2img с одной референсной картинкой.

https://elysiumai.garden/docs/novelai

## Как выбрать модель

В каталоге NovelAI показан четырьмя карточками: V4.5 Curated, V4.5 Full, V5 Curated и V5 Full. Внутри карточки выберите разрешение и 20, 24 или 28 шагов, затем скопируйте получившийся точный model ID.

| Часть ID | Значение |
| --- | --- |
| novelai/nai-diffusion-4-5-… | NovelAI V4.5 |
| novelai/nai-diffusion-5-… | NovelAI V5 |
| curated / full | Версия датасета |
| 1024x1024 | Разрешение |
| s20 / s24 / s28 | Количество шагов |

> Разрешение и шаги уже зашиты в model ID. Поле size не требуется и не меняет выбранный SKU.

## Text-to-image

Для обычной генерации используйте OpenAI-совместимый endpoint изображений. Ответ содержит изображение в data[0].b64_json.

### POST /v1/images/generations

```bash
curl https://elysiumai.garden/v1/images/generations   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "novelai/nai-diffusion-5-curated-1024x1024-s20",
    "prompt": "1girl, detailed eyes, cinematic light",
    "negative_prompt": "low quality, blurry"
  }'
```

## Img2img с референсом

Референс передаётся через Chat Completions как один content-part типа image_url. Поддерживаются публичный HTTPS URL и data URL. Текстовый part содержит промпт; negative_prompt можно передать на верхнем уровне запроса.

### POST /v1/chat/completions

```json
{
  "model": "novelai/nai-diffusion-5-full-1024x1024-s24",
  "stream": false,
  "negative_prompt": "low quality, blurry",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "same character, night city, detailed illustration"},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
    ]
  }]
}
```

> NovelAI принимает ровно одну входную картинку. Запрос с двумя и более image_url будет отклонён до обращения к провайдеру.

## Форматы и ограничения

- POST /v1/images/generations — генерация только из текста.
- POST /v1/chat/completions — генерация из текста или img2img с одной картинкой.
- Референс нельзя передать через /v1/images/generations: используйте vision-формат Chat Completions.
- Внешние клиенты видят все 96 точных SKU через GET /v1/models.
- Цена указана за одно выходное изображение и зависит от точного SKU.

---

# Кэш контекста

Как повторное использование длинного контекста отражается в usage и стоимости запроса.

https://elysiumai.garden/docs/cache

## Кэш простыми словами

Представьте длинную инструкцию и документ, которые отправляются в каждом сообщении. В первом запросе повторяемая часть может быть записана в кэш. В следующем запросе тот же фрагмент читается из кэша, а новым входом остаётся только добавленное сообщение.

- Первый запрос: длинный общий контекст + вопрос.
- Повторный запрос: тот же контекст + новый вопрос.
- В usage появляются cache_write_tokens или cache_read_tokens.
- Каждая часть умножается на свою цену за 1 миллион токенов из карточки модели.

[Кэш простыми словами](https://elysiumai.garden/docs/cache#simple)

## Как повысить повторное использование

- Ставьте неизменные инструкции и большой документ в начало контекста.
- Не меняйте пробелы, порядок блоков и служебный текст в уже отправленном префиксе.
- Добавляйте новые сообщения после стабильной части.
- Проверяйте cache_read_tokens в usage и Analytics на повторных запросах.

## Формула списания

Сначала определяется обычный, отдельно не тарифицируемый вход. В OpenAI-формате cache-токены часто уже находятся внутри prompt_tokens, поэтому повторно прибавлять полный prompt_tokens нельзя. Elysium AI выполняет эту нормализацию автоматически.

### Formula

```text
uncached_input = prompt_tokens - cache_read_tokens - cache_write_tokens

cost =
  uncached_input      / 1 000 000 × input_price
+ cache_read_tokens  / 1 000 000 × cache_read_price
+ cache_write_tokens / 1 000 000 × cache_write_price
+ output_tokens      / 1 000 000 × output_price
```

> Все четыре цены задаются в долларах за 1 миллион токенов. Это абсолютные тарифы, а не множители x.

## Поля usage

| Поле | Расчёт |
| --- | --- |
| prompt_tokens | полный OpenAI-вход; перед ручным расчётом вычтите отдельно показанные cache-токены |
| input_tokens | для Anthropic обычно уже означает обычный вход без cache |
| completion_tokens | выход × output price |
| cache_read_tokens | чтение × cache read price |
| cache_write_tokens | запись × cache write price |

---

# Доступные API-маршруты

Основные маршруты, которые нужны для подключения приложения.

https://elysiumai.garden/docs/api/endpoints

## Основные маршруты

| Метод | Маршрут | Назначение |
| --- | --- | --- |
| GET | /v1/models | Список моделей |
| GET | /v1/balance | Баланс аккаунта |
| POST | /v1/chat/completions | Диалог, tools и мультимодальный ввод |
| POST | /v1/responses | Responses-совместимый запрос |
| POST | /v1/embeddings | Векторные представления |
| POST | /v1/images/generations | Создание изображений |
| POST | /v1/images/edits | Редактирование изображений |
| POST | /v1/video/generations | Создание видео |
| POST | /v1/messages | Anthropic Messages |
| POST | /v1/messages/count_tokens | Локальная оценка токенов Anthropic |
| POST | /compatible/v1beta/models/{model}:generateContent | Gemini generateContent |
| GET | /embed/image:{model} | Готовое изображение как бинарный ответ |
| POST | /v1/audio/transcriptions | Распознавание речи |
| POST | /v1/audio/speech | Синтез речи |
| POST | /v1/rerank | Переранжирование документов |

> Доступность конкретного формата проверяйте в карточке выбранной модели.

---

# Chat Completions

Основной формат для диалогов и генерации текста.

https://elysiumai.garden/docs/api/chat-completions

## Тело запроса

### JSON

```json
{
  "model": "your-model-id",
  "messages": [
    {"role": "system", "content": "Отвечай кратко."},
    {"role": "user", "content": "Что такое API?"}
  ],
  "temperature": 0.4,
  "max_tokens": 300,
  "stream": false
}
```

## Главные поля

| Поле | Описание |
| --- | --- |
| model | Точный ID из каталога |
| messages | История сообщений с ролями system, user, assistant и tool |
| stream | true для получения ответа частями |
| max_tokens / max_output_tokens | Максимальная длина ответа |
| temperature | Степень вариативности, если модель поддерживает |
| tools | JSON-схемы функций, доступных модели |
| tool_choice | Автоматический или принудительный выбор функции |
| response_format | Требуемый формат ответа, если поддерживается |

## Вызов функций

Передайте список tools с JSON Schema аргументов. Если модель вернула tool_calls, выполните функцию в своём приложении, добавьте результат сообщением role: tool и отправьте историю повторно.

### JSON

```json
{
  "model": "your-model-id",
  "messages": [{"role": "user", "content": "Какая погода в Москве?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Получить текущую погоду",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
```

> Наличие поля tools в API не означает, что его понимает каждая модель. Проверяйте поддерживаемые endpoints и возможности карточки модели.

## Текст и изображение на входе

Для vision-модели content сообщения может быть массивом частей. Изображение передавайте публичной HTTPS-ссылкой либо data URL; закрытая ссылка с cookie серверу недоступна.

### JSON

```json
{
  "model": "your-vision-model-id",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Что изображено?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]
  }]
}
```

## Формат ответа

1. messages
2. POST
3. модель
4. choices

```
POST /v1/chat/completions
Authorization: Bearer sk-...
Content-Type: application/json

{
  "model": "your-model-id",
  "messages": [
    {"role": "user", "content": "Привет!"}
  ]
}
```

```
HTTP/1.1 200 OK
Content-Type: application/json

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Привет! Чем помочь?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 7,
    "total_tokens": 16
  }
}
```

## Потоковый ответ

Установите stream: true, чтобы получать фрагменты ответа по мере генерации. Каждый фрагмент приходит как Server-Sent Event, а завершение потока обозначается строкой [DONE].

### curl -N

```bash
curl -N https://elysiumai.garden/v1/chat/completions   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"your-model-id","stream":true,"messages":[{"role":"user","content":"Привет"}]}'
```

---

# Embeddings

Преобразование текста в числовые векторы для поиска, RAG и сравнения.

https://elysiumai.garden/docs/api/embeddings

## Пример запроса

Поле input принимает строку, массив строк, массив token ID или массив массивов token ID. Числовые token ID учитываются без повторной токенизации.

### curl

```bash
curl https://elysiumai.garden/v1/embeddings   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"your-embedding-model-id","input":["первый текст","второй текст"]}'
```

## Формы входа и параметры

| Поле | Допустимое значение | Назначение |
| --- | --- | --- |
| input | строка или массив строк | Один или несколько текстов |
| input | массив token ID | Один уже токенизированный текст |
| input | массив массивов token ID | Пакет токенизированных текстов |
| encoding_format | float или base64 | Формат вектора, если модель поддерживает |
| dimensions | целое число | Уменьшенная размерность, если поддерживается |

> Не смешивайте строки и массивы token ID в одном input. Максимальная длина и dimensions зависят от выбранной embedding-модели.

## Как читать ответ

Для каждого элемента input возвращается объект data с полем embedding. Порядок элементов в data соответствует порядку входных строк.

### JSON

```json
{
  "data": [
    {"index": 0, "embedding": [0.012, -0.084, 0.031]},
    {"index": 1, "embedding": [0.019, -0.071, 0.028]}
  ],
  "usage": {"prompt_tokens": 6, "total_tokens": 6}
}
```

---

# Responses API

Единый формат OpenAI Responses для текста, мультимодального ввода, tools и потоковой выдачи.

https://elysiumai.garden/docs/api/responses

## Минимальный запрос

Передайте точный model ID и поле input. Input может быть обычной строкой или массивом структурированных сообщений и частей контента.

### curl

```bash
curl https://elysiumai.garden/v1/responses   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "your-responses-model-id",
    "input": "Объясни API одним предложением",
    "max_output_tokens": 300
  }'
```

## Основные поля

| Поле | Назначение |
| --- | --- |
| model | Модель с поддержкой Responses |
| input | Строка или структурированный массив входа |
| instructions | Инструкция верхнего уровня |
| max_output_tokens | Ограничение длины ответа |
| tools | Инструменты и функции, доступные модели |
| tool_choice | Правило выбора инструмента |
| previous_response_id | Продолжение предыдущего ответа, если поддерживается upstream |
| stream | Поток событий вместо цельного JSON |

> Поддержка отдельных tools и мультимодальных частей зависит от модели. Смотрите endpoints и описание конкретной карточки.

## Текст и элементы ответа

Ответ содержит массив output. Не полагайтесь только на один фиксированный индекс: найдите элемент message, затем часть output_text. Официальные SDK обычно собирают текст в удобное поле output_text.

### JavaScript

```javascript
const response = await client.responses.create({
  model: "your-responses-model-id",
  input: "Объясни API одним предложением",
});

console.log(response.output_text);
```

## Поток событий

С stream: true возвращается последовательность типизированных SSE-событий. Обрабатывайте дельты текста и завершайте чтение после финального события, не ожидая один JSON-объект.

---

# Gemini-совместимый API

Нативные contents, parts и generationConfig через совместимый маршрут Gemini.

https://elysiumai.garden/docs/api/gemini-compatible

## Маршруты и авторизация

В поле Base URL укажите https://elysiumai.garden/compatible. Клиент добавит версию и операцию сам. Для ручного запроса используйте полный путь из таблицы.

Предпочтительный способ авторизации — Authorization: Bearer. Параметр ?key= тоже принимается для совместимости, но секрет в URL чаще попадает в историю и access-логи.

| Метод | Маршрут | Назначение |
| --- | --- | --- |
| GET | /compatible | Индекс API и точные маршруты |
| GET | /compatible/v1beta/models | Нативный список Gemini-моделей |
| GET | /compatible/v1/models | Список моделей для автоподбора в совместимых клиентах |
| GET | /compatible/models | Короткий адрес того же списка |
| POST | /compatible/v1beta/models/{model}:generateContent | Обычный ответ |
| POST | /compatible/v1beta/models/{model}:streamGenerateContent?alt=sse | Потоковый ответ |

## generateContent

### curl

```bash
curl https://elysiumai.garden/compatible/v1beta/models/google/gemini-3.1-flash-lite:generateContent   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Объясни API одним предложением"}]
    }],
    "generationConfig": {"temperature": 0.4, "maxOutputTokens": 300}
  }'
```

## Структура contents и parts

| Поле | Назначение |
| --- | --- |
| contents[] | История диалога с ролями user и model |
| parts[].text | Текстовая часть |
| parts[].inlineData | Файл или изображение в base64 |
| parts[].fileData | Ссылка на файл, если формат поддержан моделью |
| systemInstruction | Системная инструкция |
| generationConfig | Температура, лимит выхода и другие параметры генерации |
| tools | Нативные Gemini function declarations |

## Потоковая генерация

Используйте действие streamGenerateContent и alt=sse. Клиент должен читать события по мере поступления; обычный generateContent возвращает один JSON.

---

# Anthropic-совместимый API

Messages API, streaming и локальная оценка токенов для Anthropic-совместимых клиентов.

https://elysiumai.garden/docs/api/anthropic-compatible

## Два совместимых префикса

| Метод | Маршрут | Назначение |
| --- | --- | --- |
| POST | /v1/messages | Создание сообщения |
| POST | /anthropic/v1/messages | То же для клиентов с Anthropic-префиксом |
| POST | /v1/messages/count_tokens | Оценка входных токенов |
| POST | /anthropic/v1/messages/count_tokens | Оценка с Anthropic-префиксом |

> Claude Code самостоятельно добавляет /v1/messages, поэтому в ANTHROPIC_BASE_URL указывайте https://elysiumai.garden без /v1.

## Messages request

### curl

```bash
curl https://elysiumai.garden/v1/messages   -H "x-api-key: $ELYSIUM_API_KEY"   -H "anthropic-version: 2023-06-01"   -H "Content-Type: application/json"   -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 300,
    "messages": [{"role": "user", "content": "Привет!"}]
  }'
```

## Оценка токенов без генерации

count_tokens принимает тело Anthropic Messages и возвращает input_tokens. Расчёт выполняется локально: запрос не отправляется модели и не списывает баланс. Это оценка для проверки размера контекста, поэтому итоговый usage upstream может немного отличаться.

### JSON response

```json
{"input_tokens": 42}
```

## Prompt caching

Нативные cache_control-блоки передаются только модели, которая поддерживает Anthropic prompt caching. Cache read и cache write отражаются в usage и тарифицируются по отдельным ценам каталога.

> Elysium AI не добавляет автоматический smart cache. Кэширование происходит только по правилам и возможностям выбранной модели/upstream.

---

# Изображение одной ссылкой

GET-маршрут, который генерирует изображение и возвращает готовые бинарные данные для img или Markdown.

https://elysiumai.garden/docs/api/embed-images

## Генерация бинарного ответа

Модель указывается после image:, а prompt и параметры — в query string. Сервер возвращает image/png, image/jpeg или другой фактический MIME-тип, а не JSON.

### curl

```bash
curl --get "https://elysiumai.garden/embed/image:google/gemini-3.1-flash-image-preview"   -H "Authorization: Bearer $ELYSIUM_API_KEY"   --data-urlencode "prompt=Стеклянный павильон в туманном лесу"   --data-urlencode "aspect_ratio=16:9"   --data-urlencode "image_size=2K"   --output result.png
```

## Использование в HTML и Markdown

Тег img не умеет отправлять Authorization, поэтому для прямого встраивания допускается ?key=. Используйте отдельный ключ с небольшим бюджетом и не размещайте его на публичной странице: URL может сохраниться в истории браузера, аналитике и логах.

### HTML

```html
<img
  src="https://elysiumai.garden/embed/image:google/gemini-3.1-flash-image-preview?prompt=Marble%20garden&aspect_ratio=16:9&key=sk-..."
  alt="Сгенерированный сад"
/>
```

## Поддерживаемые параметры

| Параметр | Назначение |
| --- | --- |
| prompt | Описание создаваемого изображения; обязательно |
| aspect_ratio | Соотношение сторон, например 1:1 или 16:9 |
| image_size | Разрешение вроде 1K или 2K, если модель поддерживает |
| key | API-ключ для клиентов, которые не могут отправить заголовок |

> Параметр references здесь намеренно не поддерживается. Для правки исходного изображения используйте POST /v1/images/edits или Gemini Image через Chat Completions.

## Стоимость и хранение

Каждый GET запускает новую генерацию и тарифицируется как обычный запрос выбранной image-модели. Ответ помечен private, no-store: Elysium AI не реализует smart cache и не обещает повторно вернуть прежнюю картинку по тому же URL.

> Если результат нужен повторно, сохраните бинарные данные в собственное хранилище и показывайте уже сохранённый URL.

---

# Музыка и речь

Музыка Suno, речь ElevenLabs и Gemini, обработка аудио.

https://elysiumai.garden/docs/api/audio

## От описания к медиафайлу

![Прозрачная стеклянная киноплёнка переходит в объёмную звуковую волну.](https://elysiumai.garden/images/docs/video-audio-liquid-glass.png)

Иллюстрация работы с видео и аудио. Один запуск, проверка статуса задачи, затем сохранение готового файла.

## Создать аудиозадачу

POST /v1/audio/generations создаёт асинхронную задачу. GET /v1/audio/generations/{id} возвращает queued, processing, completed или failed. После завершения tracks содержит все файлы и их публичные ID. Музыка может вернуть два трека — это результаты одного запроса генерации. Это отдельный JSON API, а не синхронный бинарный /v1/audio/speech.

### Music

```json
{"model":"suno/music","prompt":"Спокойная фортепианная музыка","input":{"model":"V5_5","customMode":false,"instrumental":true}}
```

### Speech

```json
{"model":"elevenlabs/text-to-speech-turbo-2-5","prompt":"Здравствуйте!","input":{"voice":"TX3LPaxmHKxFdv7VOQHJ","stability":0.5,"speed":1}}
```

### Poll

```bash
curl "https://elysiumai.garden/v1/audio/generations/$TASK_ID" -H "Authorization: Bearer $ELYSIUM_API_KEY"
```

> Верхний model выбирает публичное семейство. input.model задаёт версию Suno. Это разные поля.

## Голоса и обработка аудио

В LibreChat выберите ElysiumAI Audio. Выбор голосов и редактор реплик используют схему конкретной модели. Если диалог не задан, сообщение озвучивается стандартным голосом. Для своей песни включите customMode, задайте style и title; сообщение станет текстом песни. Для обработки загруженного аудио укажите доступный HTTPS URL. Продолжение, разделение и WAV могут требовать audioId вида task_public:0 из вашей завершённой задачи. Внутренние ID треков и задач других сервисов не принимаются.

> Обрабатывайте только аудио, на использование которого у вас есть разрешение. Не повторяйте автоматически запрос после неоднозначного таймаута: сначала проверьте имеющуюся задачу. Исходное аудио пока передаётся ссылкой.

## Цена до генерации

POST /v1/media/quote принимает те же model, operation, prompt и input, что и генерация. Платная задача не запускается. В billing возвращаются ставки, известные объёмы, pending для ещё неизвестного результата. Файлы должны быть доступны по публичным HTTPS URL. Полная таблица — в раскрытой карточке модели: цена может зависеть от разрешения, длительности, звука, качества и входных файлов.

### Quote

```bash
curl https://elysiumai.garden/v1/media/quote -H "Authorization: Bearer $ELYSIUM_API_KEY" -H "Content-Type: application/json" -d '{"model":"openai/gpt-image-2","prompt":"A garden","input":{"resolution":"2K"}}'
```

> Предварительный расчёт принимает JSON с публичными ссылками на файлы. Он не загружает локальные файлы и не раскрывает ID предыдущих задач. Операции с такими исходниками проверяются и тарифицируются при отправке; предварительный расчёт доступен не для всех этих вариантов.

## Параметры конкретной модели

GET /v1/media/models возвращает публичные ID моделей, режимы operations и схемы input: допустимые значения, обязательные поля, ограничения и значения по умолчанию. Выберите operation из ответа и передайте параметры этого режима внутри input. Разрешение, длительность, референсы и звук зависят от модели; у некоторых сочетаний есть дополнительные ограничения. Пропущенные поля используют настройки модели, а явно переданные false и 0 сохраняются.

### Catalog

```bash
curl https://elysiumai.garden/v1/media/models
```

> Не переносите разрешение или качество из другой модели. Неизвестные поля input отклоняются до генерации. Проверка параметров не может заранее предсказать модерацию содержимого или временный сбой генерации.

## Оплата и хранение результата

У каждой модели фиксированные ставки в USD по режимам и параметрам. Ставка сохраняется при запуске и не меняется из-за последующей смены цены поставщика. Итог = ставка × объём плюс отдельно указанные доплаты за входные файлы. Единицы: изображения, секунды видео/аудио, 1000 символов текста или готовые операции. Точная сумма списывается один раз после готовности результата, по фактическому объёму и сохранённым ставкам. До завершения средства блокируются внутренне, без изменения баланса и операции списания в истории. При ошибке блокировка снимается без списания и операции возврата.  Настроенные скидки аккаунта учитываются. Расшифровка находится в billing, у видео — metadata.billing, а также в истории запросов. Gemini TTS: $0,0011 за фактическую секунду результата ($0,066/мин), обработка текста включена; это цена до скидок аккаунта.

Ссылки на результат временные и дают доступ любому, кто их получил. Сохраняйте файлы сразу. Срок ссылки — не более 13 дней; она может перестать работать раньше, если исходный файл удалён.

> Каждая новая отправка — отдельная платная задача. Сетевой таймаут не означает, что генерация не запустилась. Не повторяйте отправку автоматически.

## LibreChat Studio

Выберите ElysiumAI Images или ElysiumAI Video, затем модель и «Настройки генерации» рядом с полем сообщения. Форма строится по схеме выбранной модели. Смена режима очищает старые параметры, настройки привязаны к модели. Описание пишите в сообщении; картинки прикрепляйте к нему либо указывайте доступные ссылки. Для сложных структур сцен и референсов есть поле JSON.

Во время запроса показана лёгкая анимация ожидания — это не оценка процента готовности. Она приостанавливается за пределами экрана и в скрытой вкладке, учитывает уменьшение движения. Готовые изображения и видео появляются прямо в чате. Для видео- и аудиореференсов используйте публичные URL: загрузка этих файлов напрямую через мост не поддерживается.

---

# Изображения

Генерация, редактирование и обработка с параметрами выбранной модели.

https://elysiumai.garden/docs/api/images

## Одна модель — несколько режимов

Суффикс вроде -edit обычно обозначает операцию редактирования, а не отдельное семейство. В ElysiumAI поддерживаемые операции объединены под одним публичным model ID и одной карточкой. Не нужно самостоятельно дописывать -edit к ID. В карточке указаны доступные режимы и отдельные таблицы цен для них. Flare и Sunburst остаются разными вариантами модели; у каждого свои режимы создания и редактирования.

![В двух стеклянных рамках — одно горное озеро до и после изменения освещения на закатное.](https://elysiumai.garden/images/docs/image-editing-liquid-glass.png)

Концептуальная иллюстрация: редактирование начинается с исходной картинки. Это не сравнительный тест моделей и не обещание конкретного результата.

| Задача | Что передать | API |
| --- | --- | --- |
| Создать с нуля | model + prompt + input | POST /v1/images/generations |
| Изменить готовую картинку | model + prompt + image + input | POST /v1/images/edits |
| Увеличение, слои, сегментация | Явный operation и обязательные поля его схемы | POST /v1/images/edits |

> Редактирование поддерживается не каждой моделью. Работа с референсами не означает поддержку маски или гарантированное сохранение лица и композиции. Режим доступен только если он указан в схеме модели.

## Автоматический или явный выбор режима

Если operation не указан, исходная картинка выбирает поддерживаемый режим image-to-image, image-edit или edit. Без картинки выбирается режим генерации по умолчанию. У моделей с единым режимом generate референсы передаются в него же. Для совместимости /images/generations тоже принимает исходные изображения; для /images/edits исходная картинка обязательна.

Для предсказуемой интеграции получите operations через GET /v1/media/models и задайте точное имя режима. Явный operation имеет приоритет над автоматическим выбором. Увеличение, правка области и разделение на слои не выбираются по обычному вложению: укажите их явно. Неподдерживаемые сочетания отклоняются, а не превращаются незаметно в другую генерацию.

### Model operations

```bash
curl -s https://elysiumai.garden/v1/media/models | jq '.data[] | select(.id == "openai/gpt-image-2.5-flare") | {id, operations, tariff}'
```

## Редактирование по ссылке на картинку

Храните API-ключ в переменной окружения на сервере. Замените ссылку в примере на доступное HTTPS-изображение, которое вам разрешено обрабатывать. Верхнее поле image — удобный общий формат; шлюз преобразует его в поле выбранной модели. Собственные настройки модели передаются внутри input.

### curl · JSON

```bash
curl https://elysiumai.garden/v1/images/edits \
  --max-time 660 \
  -H "Authorization: Bearer $ELYSIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-flare",
    "operation": "image-to-image",
    "prompt": "Change the lighting to sunset. Keep the composition.",
    "image": "https://example.com/source.png",
    "input": {"resolution": "2K", "aspect_ratio": "16:9"},
    "response_format": "url"
  }'
```

### Python · requests

```python
import os
import requests

response = requests.post(
    "https://elysiumai.garden/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['ELYSIUM_API_KEY']}"},
    json={
        "model": "openai/gpt-image-2.5-flare",
        "operation": "image-to-image",
        "prompt": "Change the lighting to sunset. Keep the composition.",
        "image": "https://example.com/source.png",
        "input": {"resolution": "2K", "aspect_ratio": "16:9"},
    },
    timeout=(15, 660),
)
response.raise_for_status()
result = response.json()
print(result["data"][0]["url"])
print(result.get("billing"))
```

> JSON-ответ содержит готовый результат, а не задачу для опроса: data[].url либо data[].b64_json и расшифровку billing. Исходная ссылка должна вести на сам файл изображения, а не на галерею или страницу входа.

## Локальный файл и несколько референсов

- Не задавайте Content-Type вручную для multipart: curl сам добавляет границу частей запроса.
- Наш лимит multipart — 20 МБ на изображение. Дополнительно действуют ограничения модели на формат и число референсов; GPT Image 2.5 принимает до 16 референсов.
- Для нескольких файлов повторите -F image=@файл. Не дублируйте одни и те же изображения одновременно в image и input_urls.
- Маски поддерживаются не везде. Передавайте маску только при наличии соответствующего поля в схеме выбранного режима. У GPT Image 2.5 поле маски не заявлено.

### curl · multipart

```bash
curl https://elysiumai.garden/v1/images/edits \
  --max-time 660 \
  -H "Authorization: Bearer $ELYSIUM_API_KEY" \
  -F 'model=openai/gpt-image-2.5-flare' \
  -F 'operation=image-to-image' \
  -F 'prompt=Change the lighting to sunset. Keep the composition.' \
  -F 'image=@./source.png' \
  -F 'input={"resolution":"2K","aspect_ratio":"16:9"}'
```

### Multiple references · JSON

```json
{
  "model": "openai/gpt-image-2.5-sunburst",
  "operation": "image-to-image",
  "prompt": "Use the composition of the first image and the palette of the second.",
  "input": {
    "input_urls": ["https://example.com/composition.png", "https://example.com/palette.png"],
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }
}
```

## Grok: маски областей

Для grok-imagine-image-2-0 режим segment-map принимает либо input.image_url, либо input.task_id из предыдущего успешного запроса изображения этого же аккаунта. Передавайте только один исходник. Оба варианта работают через /v1/images/generations и /v1/images/edits. Каждый элемент data содержит маску: url (или b64_json), index и name. Индексы возвращаются без изменений, включая нулевой; сохраняйте их при обработке масок.

### Image URL

```json
{"model":"grok-imagine-image-2-0","operation":"segment-map","input":{"image_url":"https://example.com/source.png"}}
```

### Previous task

```json
{"model":"grok-imagine-image-2-0","operation":"segment-map","input":{"task_id":"task_returned_by_previous_request"}}
```

## Сколько стоит редактирование

Редактирование — отдельный платный результат. Его фиксированная ставка может отличаться от создания с нуля, зависеть от разрешения и включать плату за входные изображения. Перед запуском получите бесплатный расчёт с теми же model, operation, prompt, ссылкой image и input. Редактирование не становится бесплатным, если за исходную картинку уже было заплачено.

| GPT Image 2.5 · Flare / Sunburst | Создание / изображение | Редактирование / изображение |
| --- | --- | --- |
| 1K | $0.045 | $0.045 |
| 2K | $0.075 | $0.075 |
| 4K | $0.12 | $0.12 |

### Quote an edit

```bash
curl https://elysiumai.garden/v1/media/quote \
  -H "Authorization: Bearer $ELYSIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-image-2.5-flare","operation":"image-to-image","prompt":"Sunset lighting","image":"https://example.com/source.png","input":{"resolution":"2K","aspect_ratio":"16:9"}}'
```

> Ставки указаны до персональных скидок на 9 сентября 2026 года. Актуальный источник — каталог и расчёт quote. У GPT Image 2.5 пропорции 27:16, 16:27, 9:8 и 8:9 доступны только в 1K: их нельзя сочетать с 2K или 4K. Расчёт quote не закрепляет цену: ставка сохраняется при отправке генерации.

## Те же режимы в LibreChat

- Выберите ElysiumAI Images и нужную модель. Отдельная модель с -edit не нужна.
- Откройте «Настройки генерации». В автоматическом режиме вложенная картинка выбирает редактирование; текущий режим подписан рядом с полем сообщения. Можно выбрать operation явно.
- Прикрепите исходную картинку к текущему сообщению и напишите, что изменить. Предыдущие картинки в чате не становятся исходником автоматически: прикрепите нужное изображение снова.
- Проверьте разрешение и таблицу цен. Для слоёв, маски или увеличения выберите соответствующий поддерживаемый режим и заполните его обязательные поля.
- Смена режима очищает старые параметры; смена модели не переносит чужие настройки. Перед платным запуском сервер проверяет итоговый запрос.

> Проверка параметров не гарантирует доступность провайдера, прохождение модерации и художественное качество. Таймаут не доказывает ошибку генерации: не повторяйте платный запрос автоматически.

## Создать или изменить изображение

Для моделей из /v1/media/models используйте POST /v1/images/generations или /v1/images/edits. В их числе основные ID GPT Image и Gemini Image. Другие модели каталога могут использовать Chat Completions — проверяйте endpoints в карточке. Ответ изображения дожидается завершения и содержит data[].url либо data[].b64_json. Установите таймаут клиента не менее 10 минут.

### curl

```bash
curl https://elysiumai.garden/v1/images/generations   --max-time 660   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"openai/gpt-image-2","prompt":"A white marble garden by the sea","input":{"resolution":"1K","aspect_ratio":"1:1"},"response_format":"url"}'
```

### Edit

```json
{"model":"openai/gpt-image-2","operation":"image-to-image","prompt":"Make the sky orange","input":{"image_urls":["https://example.com/source.png"],"resolution":"1K","aspect_ratio":"1:1"}}
```

> Изображения также можно загрузить через multipart-поля image (до 20 МБ каждое). Маски, несколько референсов, увеличение и сегментация задаются по схеме выбранного режима. По умолчанию один результат; n > 1 доступно только при поддержке моделью.

## Цена до генерации

POST /v1/media/quote принимает те же model, operation, prompt и input, что и генерация. Платная задача не запускается. В billing возвращаются ставки, известные объёмы, pending для ещё неизвестного результата. Файлы должны быть доступны по публичным HTTPS URL. Полная таблица — в раскрытой карточке модели: цена может зависеть от разрешения, длительности, звука, качества и входных файлов.

### Quote

```bash
curl https://elysiumai.garden/v1/media/quote -H "Authorization: Bearer $ELYSIUM_API_KEY" -H "Content-Type: application/json" -d '{"model":"openai/gpt-image-2","prompt":"A garden","input":{"resolution":"2K"}}'
```

> Предварительный расчёт принимает JSON с публичными ссылками на файлы. Он не загружает локальные файлы и не раскрывает ID предыдущих задач. Операции с такими исходниками проверяются и тарифицируются при отправке; предварительный расчёт доступен не для всех этих вариантов.

## Параметры конкретной модели

GET /v1/media/models возвращает публичные ID моделей, режимы operations и схемы input: допустимые значения, обязательные поля, ограничения и значения по умолчанию. Выберите operation из ответа и передайте параметры этого режима внутри input. Разрешение, длительность, референсы и звук зависят от модели; у некоторых сочетаний есть дополнительные ограничения. Пропущенные поля используют настройки модели, а явно переданные false и 0 сохраняются.

### Catalog

```bash
curl https://elysiumai.garden/v1/media/models
```

> Не переносите разрешение или качество из другой модели. Неизвестные поля input отклоняются до генерации. Проверка параметров не может заранее предсказать модерацию содержимого или временный сбой генерации.

## Оплата и хранение результата

У каждой модели фиксированные ставки в USD по режимам и параметрам. Ставка сохраняется при запуске и не меняется из-за последующей смены цены поставщика. Итог = ставка × объём плюс отдельно указанные доплаты за входные файлы. Единицы: изображения, секунды видео/аудио, 1000 символов текста или готовые операции. Точная сумма списывается один раз после готовности результата, по фактическому объёму и сохранённым ставкам. До завершения средства блокируются внутренне, без изменения баланса и операции списания в истории. При ошибке блокировка снимается без списания и операции возврата.  Настроенные скидки аккаунта учитываются. Расшифровка находится в billing, у видео — metadata.billing, а также в истории запросов. Gemini TTS: $0,0011 за фактическую секунду результата ($0,066/мин), обработка текста включена; это цена до скидок аккаунта.

Ссылки на результат временные и дают доступ любому, кто их получил. Сохраняйте файлы сразу. Срок ссылки — не более 13 дней; она может перестать работать раньше, если исходный файл удалён.

> Каждая новая отправка — отдельная платная задача. Сетевой таймаут не означает, что генерация не запустилась. Не повторяйте отправку автоматически.

## LibreChat Studio

Выберите ElysiumAI Images или ElysiumAI Video, затем модель и «Настройки генерации» рядом с полем сообщения. Форма строится по схеме выбранной модели. Смена режима очищает старые параметры, настройки привязаны к модели. Описание пишите в сообщении; картинки прикрепляйте к нему либо указывайте доступные ссылки. Для сложных структур сцен и референсов есть поле JSON.

Во время запроса показана лёгкая анимация ожидания — это не оценка процента готовности. Она приостанавливается за пределами экрана и в скрытой вкладке, учитывает уменьшение движения. Готовые изображения и видео появляются прямо в чате. Для видео- и аудиореференсов используйте публичные URL: загрузка этих файлов напрямую через мост не поддерживается.

---

# Генерация видео

Асинхронные видеозадачи, референсы и воспроизведение в LibreChat.

https://elysiumai.garden/docs/api/video

## От описания к медиафайлу

![Прозрачная стеклянная киноплёнка переходит в объёмную звуковую волну.](https://elysiumai.garden/images/docs/video-audio-liquid-glass.png)

Иллюстрация работы с видео и аудио. Один запуск, проверка статуса задачи, затем сохранение готового файла.

## Один запуск, затем проверка статуса

POST /v1/videos (также /v1/video/generations) возвращает публичный id задачи и status. Проверяйте GET /v1/videos/{id} раз в 3–5 секунд до completed или failed. Готовая ссылка находится в metadata.url. Это относится к медиакаталогу, включая Gemini Omni и Seedance: старый синхронный ответ videos[] здесь больше не используется. LibreChat ждёт результат автоматически до 10 минут.

### Create

```bash
curl https://elysiumai.garden/v1/videos   -H "Authorization: Bearer $ELYSIUM_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"x-ai/grok-imagine-video","operation":"text-to-video","prompt":"A quiet ocean at sunrise","input":{"duration":6,"resolution":"480p","aspect_ratio":"16:9"}}'
```

### Poll

```bash
curl "https://elysiumai.garden/v1/videos/$TASK_ID" -H "Authorization: Bearer $ELYSIUM_API_KEY"
```

### Completed

```json
{"id":"task_public_id","object":"video","status":"completed","metadata":{"url":"https://elysiumai.garden/v1/media/opaque-token"}}
```

> Режимы референсов и обработки могут требовать URL изображений, видео, аудио либо публичный ID предыдущей завершённой задачи вашего аккаунта. Имена полей input берите из схемы. Не все режимы доступны у каждой модели.

## Цена до генерации

POST /v1/media/quote принимает те же model, operation, prompt и input, что и генерация. Платная задача не запускается. В billing возвращаются ставки, известные объёмы, pending для ещё неизвестного результата. Файлы должны быть доступны по публичным HTTPS URL. Полная таблица — в раскрытой карточке модели: цена может зависеть от разрешения, длительности, звука, качества и входных файлов.

### Quote

```bash
curl https://elysiumai.garden/v1/media/quote -H "Authorization: Bearer $ELYSIUM_API_KEY" -H "Content-Type: application/json" -d '{"model":"openai/gpt-image-2","prompt":"A garden","input":{"resolution":"2K"}}'
```

> Предварительный расчёт принимает JSON с публичными ссылками на файлы. Он не загружает локальные файлы и не раскрывает ID предыдущих задач. Операции с такими исходниками проверяются и тарифицируются при отправке; предварительный расчёт доступен не для всех этих вариантов.

## Параметры конкретной модели

GET /v1/media/models возвращает публичные ID моделей, режимы operations и схемы input: допустимые значения, обязательные поля, ограничения и значения по умолчанию. Выберите operation из ответа и передайте параметры этого режима внутри input. Разрешение, длительность, референсы и звук зависят от модели; у некоторых сочетаний есть дополнительные ограничения. Пропущенные поля используют настройки модели, а явно переданные false и 0 сохраняются.

### Catalog

```bash
curl https://elysiumai.garden/v1/media/models
```

> Не переносите разрешение или качество из другой модели. Неизвестные поля input отклоняются до генерации. Проверка параметров не может заранее предсказать модерацию содержимого или временный сбой генерации.

## Оплата и хранение результата

У каждой модели фиксированные ставки в USD по режимам и параметрам. Ставка сохраняется при запуске и не меняется из-за последующей смены цены поставщика. Итог = ставка × объём плюс отдельно указанные доплаты за входные файлы. Единицы: изображения, секунды видео/аудио, 1000 символов текста или готовые операции. Точная сумма списывается один раз после готовности результата, по фактическому объёму и сохранённым ставкам. До завершения средства блокируются внутренне, без изменения баланса и операции списания в истории. При ошибке блокировка снимается без списания и операции возврата.  Настроенные скидки аккаунта учитываются. Расшифровка находится в billing, у видео — metadata.billing, а также в истории запросов. Gemini TTS: $0,0011 за фактическую секунду результата ($0,066/мин), обработка текста включена; это цена до скидок аккаунта.

Ссылки на результат временные и дают доступ любому, кто их получил. Сохраняйте файлы сразу. Срок ссылки — не более 13 дней; она может перестать работать раньше, если исходный файл удалён.

> Каждая новая отправка — отдельная платная задача. Сетевой таймаут не означает, что генерация не запустилась. Не повторяйте отправку автоматически.

## LibreChat Studio

Выберите ElysiumAI Images или ElysiumAI Video, затем модель и «Настройки генерации» рядом с полем сообщения. Форма строится по схеме выбранной модели. Смена режима очищает старые параметры, настройки привязаны к модели. Описание пишите в сообщении; картинки прикрепляйте к нему либо указывайте доступные ссылки. Для сложных структур сцен и референсов есть поле JSON.

Во время запроса показана лёгкая анимация ожидания — это не оценка процента готовности. Она приостанавливается за пределами экрана и в скрытой вкладке, учитывает уменьшение движения. Готовые изображения и видео появляются прямо в чате. Для видео- и аудиореференсов используйте публичные URL: загрузка этих файлов напрямую через мост не поддерживается.

---

# Подключение готовых приложений

Выберите программу, укажите адрес Elysium AI, API-ключ и точный ID модели — остальное клиент сделает сам.

https://elysiumai.garden/docs/integrations/overview

## Три значения для любого подключения

Base URL говорит приложению, куда отправлять запросы. API-ключ подтверждает доступ к вашему балансу. Model ID выбирает модель. Эти значения обычно находятся в разделах Provider, API, Connection или Custom endpoint.

| Поле | Что указать | Где взять |
| --- | --- | --- |
| Base URL | https://elysiumai.garden/v1 | Скопировать отсюда |
| API key | sk-... | Кабинет → API-ключи |
| Model | точный model ID | Каталог моделей |

> Не добавляйте /chat/completions к Base URL, если приложение просит именно базовый адрес. Полный маршрут нужен только в полях Endpoint или Proxy URL.

## Куда вставлять команды

Команды из документации вводятся не на сайте Elysium AI, а в терминале вашего компьютера. Выберите вкладку своей системы, откройте указанную программу и вставляйте команды по одной, нажимая Enter после каждой строки.

| Система | Что открыть | Как открыть |
| --- | --- | --- |
| Windows · PowerShell | PowerShell или Windows Terminal | Пуск → введите PowerShell → Открыть |
| Windows · CMD | Командная строка | Win + R → cmd → Enter |
| macOS | Terminal | Cmd + Space → Terminal → Enter |
| Linux | Terminal | Ctrl + Alt + T или Terminal из меню приложений |

### PowerShell

```powershell
$env:ELYSIUM_API_KEY="sk-..."
# Проверка: команда должна вывести начало ключа
$env:ELYSIUM_API_KEY.Substring(0, 3)
```

### Windows CMD

```bat
set ELYSIUM_API_KEY=sk-...
rem Проверка: команда выведет сохранённое значение
echo %ELYSIUM_API_KEY%
```

### macOS

```bash
export ELYSIUM_API_KEY="sk-..."
# Проверка
echo "$ELYSIUM_API_KEY"
```

### Linux

```bash
export ELYSIUM_API_KEY="sk-..."
# Проверка
echo "$ELYSIUM_API_KEY"
```

> Переменная действует в текущем окне терминала. Если закрыть окно, для следующего запуска задайте её снова либо используйте постоянную конфигурацию из руководства конкретного приложения.

## Краткая шпаргалка

| Клиент | Протокол | Base URL |
| --- | --- | --- |
| OpenAI SDK / SillyTavern / Hermes / OpenClaw | OpenAI-compatible | https://elysiumai.garden/v1 |
| Codex | Responses | https://elysiumai.garden/v1 |
| Claude Code | Anthropic Messages | https://elysiumai.garden |

### Environment

```bash
export ELYSIUM_API_KEY="sk-..."
export OPENAI_BASE_URL="https://elysiumai.garden/v1"
```

## Выберите приложение

- [OpenAI SDK](https://elysiumai.garden/docs/integrations/openai-sdk): Python и JavaScript с официальным SDK.
- [SillyTavern](https://elysiumai.garden/docs/integrations/sillytavern): Подключение через Custom OpenAI-compatible endpoint.
- [Janitor AI](https://elysiumai.garden/docs/integrations/janitor-ai): Настройка собственного proxy URL и модели.
- [OpenClaw](https://elysiumai.garden/docs/integrations/openclaw): Провайдер Elysium AI в конфигурации агента.
- [Hermes Agent](https://elysiumai.garden/docs/integrations/hermes-agent): Интерактивный мастер или config.yaml.
- [Код и IDE](https://elysiumai.garden/docs/integrations/code-and-ide): Cline, Roo Code, Kilo Code, OpenCode, Zed, Cursor и другие инструменты для разработки.
- [Codex](https://elysiumai.garden/docs/integrations/codex): Custom provider через Responses API.
- [Claude Code](https://elysiumai.garden/docs/integrations/claude-code): Подключение через Anthropic Messages API.

---

# OpenAI SDK

Используйте официальный OpenAI-клиент, заменив API-ключ и base URL.

https://elysiumai.garden/docs/integrations/openai-sdk

## Пошаговое подключение

- Создайте API-ключ в кабинете.
- Установите библиотеку: pip install openai или npm install openai.
- Сохраните ключ в переменной ELYSIUM_API_KEY.
- Скопируйте точный ID модели из каталога и вставьте в model.

## Установка SDK в терминале

Откройте PowerShell, CMD, Terminal macOS или Terminal Linux. Для Python используйте первую команду, для Node.js — вторую. Выполнять обе не нужно.

### PowerShell

```powershell
py -m pip install openai
# или для JavaScript в папке проекта
npm install openai
```

### Windows CMD

```bat
py -m pip install openai
rem или для JavaScript в папке проекта
npm install openai
```

### macOS

```bash
python3 -m pip install openai
# или для JavaScript в папке проекта
npm install openai
```

### Linux

```bash
python3 -m pip install openai
# или для JavaScript в папке проекта
npm install openai
```

## Готовые примеры

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ELYSIUM_API_KEY"],
    base_url="https://elysiumai.garden/v1",
)

result = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Объясни API одним предложением"}],
)
print(result.choices[0].message.content)
```

### JavaScript

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ELYSIUM_API_KEY,
  baseURL: "https://elysiumai.garden/v1",
});

const result = await client.chat.completions.create({
  model: "your-model-id",
  messages: [{ role: "user", content: "Объясни API одним предложением" }],
});
console.log(result.choices[0].message.content);
```

## Минимальная конфигурация

| Параметр | Значение |
| --- | --- |
| api_key / apiKey | ELYSIUM_API_KEY |
| base_url / baseURL | https://elysiumai.garden/v1 |
| model | ID из GET /v1/models |

---

# SillyTavern

Подключите Elysium AI как пользовательский OpenAI-совместимый источник.

https://elysiumai.garden/docs/integrations/sillytavern

## Настройка интерфейса

- Откройте API Connections.
- Выберите Chat Completion и источник Custom (OpenAI-compatible).
- В Base URL укажите https://elysiumai.garden/v1.
- Вставьте ключ sk-... в API Key.
- Выберите или впишите точный ID модели из каталога, затем нажмите Connect.

## Параметры подключения

| Поле | Значение |
| --- | --- |
| API type | Chat Completion |
| Source | Custom / OpenAI-compatible |
| Base URL | https://elysiumai.garden/v1 |
| API Key | sk-... |
| Model | точный ID из каталога |

## Как проверить

После подключения отправьте короткое сообщение в новом чате. При успехе появится ответ, а запрос — во вкладке Analytics. Ошибка 401 означает проблему с ключом, 404 — обычно неверный URL или model ID.

---

# Janitor AI

Используйте Elysium AI в режиме собственного OpenAI-совместимого прокси.

https://elysiumai.garden/docs/integrations/janitor-ai

## Подключение

- Откройте настройки API в Janitor AI и выберите Custom/OpenAI-compatible proxy.
- Если поле называется Proxy URL или Endpoint, укажите полный адрес https://elysiumai.garden/v1/chat/completions.
- Если поле называется Base URL, укажите только https://elysiumai.garden/v1.
- Вставьте API-ключ и точный model ID из каталога, сохраните настройки и отправьте тестовое сообщение.

## Какой URL выбрать

| Название поля | Значение |
| --- | --- |
| Base URL | https://elysiumai.garden/v1 |
| Proxy URL / Endpoint | https://elysiumai.garden/v1/chat/completions |

## Частая ошибка

> Не вставляйте полный /chat/completions в поле Base URL: некоторые версии клиента добавляют этот путь самостоятельно, и получится двойной маршрут.

---

# OpenClaw

Добавьте Elysium AI как отдельного OpenAI-совместимого провайдера.

https://elysiumai.garden/docs/integrations/openclaw

## Перед настройкой

Сначала создайте ключ и выберите модель в каталоге. В конфигурации ниже замените your-model-id на точный ID, не сокращая его.

## Конфигурация провайдера

### openclaw.json

```json
{
  "models": {
    "providers": {
      "elysium": {
        "baseUrl": "https://elysiumai.garden/v1",
        "apiKey": "${ELYSIUM_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "your-model-id", "name": "Elysium model" }
        ]
      }
    }
  },
  "agents": {
    "defaults": { "model": { "primary": "elysium/your-model-id" } }
  }
}
```

## Проверка

- Перезапустите OpenClaw после изменения конфигурации.
- Убедитесь, что переменная ELYSIUM_API_KEY доступна процессу.
- Если модель не найдена, ещё раз скопируйте ID из каталога без изменений.

---

# Hermes Agent

Подключите Elysium AI через мастер Custom endpoint или файл конфигурации Hermes.

https://elysiumai.garden/docs/integrations/hermes-agent

## Самый простой способ

Запустите мастер выбора модели, выберите Custom endpoint и последовательно вставьте базовый URL, ключ и model ID.

| Поле мастера | Значение |
| --- | --- |
| Base URL | https://elysiumai.garden/v1 |
| API key | sk-... |
| Model | точный ID из каталога |

### Terminal

```bash
hermes model
```

## Ручная конфигурация

### ~/.hermes/config.yaml

```yaml
model:
  default: your-model-id
  provider: custom:elysium
  base_url: https://elysiumai.garden/v1

custom_providers:
  - name: elysium
    base_url: https://elysiumai.garden/v1
    api_key: sk-YOUR_KEY_HERE
    model: your-model-id
```

## Запуск

### Terminal

```bash
hermes chat
```

> Если Hermes сообщает, что модель не найдена, проверьте exact model ID через GET /v1/models.

---

# AI-клиенты для кода и IDE

Выберите редактор или coding agent, подставьте модель из живого каталога и получите готовую конфигурацию Elysium AI.

https://elysiumai.garden/docs/integrations/code-and-ide

## Соберите конфигурацию

Мастер ниже подставляет правильный Base URL, выбранную операционную систему и точный ID модели. API-ключ сюда вводить не нужно: он остаётся только в настройках клиента или системном хранилище.

[Соберите конфигурацию](https://elysiumai.garden/docs/integrations/code-and-ide#assistant)

## Как выбрать клиент

- Cline, Roo Code и Kilo Code подходят, если вы уже работаете в VS Code или совместимом редакторе.
- Zed и Cursor — самостоятельные редакторы. Для Cursor Elysium AI подключается через совместимое VS Code-расширение внутри редактора.
- OpenCode и Qwen Code удобны для терминала, автоматизации и работы по SSH.
- OAI Compatible Copilot добавляет пользовательские модели в интерфейс Copilot Chat через отдельное расширение.

> Для первого запуска используйте режим Ask, Chat или другой режим без автоматического изменения файлов. После проверки ответа включайте агентные действия осознанно.

## Гайды первой волны

- [Cline](https://elysiumai.garden/docs/integrations/cline): OpenAI Compatible в боковой панели VS Code.
- [Roo Code](https://elysiumai.garden/docs/integrations/roo-code): Профиль с нативным tool calling.
- [Kilo Code](https://elysiumai.garden/docs/integrations/kilo-code): Custom provider через интерфейс или конфигурацию.
- [OpenCode](https://elysiumai.garden/docs/integrations/opencode): Провайдер в opencode.json и выбор через /models.
- [Zed](https://elysiumai.garden/docs/integrations/zed): OpenAI-compatible provider в настройках Zed AI.
- [Cursor](https://elysiumai.garden/docs/integrations/cursor): Рабочее подключение через Cline, Roo Code или Kilo Code.
- [Qwen Code](https://elysiumai.garden/docs/integrations/qwen-code): modelProviders и ключ из переменной окружения.
- [OAI Compatible Copilot](https://elysiumai.garden/docs/integrations/oai-compatible-copilot): Пользовательский провайдер в Copilot Chat.
- [Codex](https://elysiumai.garden/docs/integrations/codex): Responses API через custom model provider.
- [Claude Code](https://elysiumai.garden/docs/integrations/claude-code): Anthropic Messages через переменные окружения.

## Безопасный первый запуск

- Создайте для IDE отдельный API-ключ с ограниченным бюджетом.
- Не сохраняйте ключ в репозитории и не вставляйте его в файлы, которые отслеживает Git.
- Начните с короткого запроса без инструментов: «Ответь одним словом: работает».
- Проверьте запрос и списание во вкладке Analytics, затем разрешайте чтение и изменение проекта.

---

# Cline

Подключите Elysium AI к Cline через встроенный провайдер OpenAI Compatible.

https://elysiumai.garden/docs/integrations/cline

## Настройка подключения

Откройте Cline, нажмите шестерёнку и выберите OpenAI Compatible. Мастер подготовит четыре значения для нового профиля.

[Настройка подключения](https://elysiumai.garden/docs/integrations/cline#setup)

## Порядок действий

- Установите Cline из магазина расширений редактора и откройте его боковую панель.
- В настройках API выберите OpenAI Compatible.
- Укажите https://elysiumai.garden/v1, вставьте отдельный API-ключ и точный Model ID из каталога.
- Если модель не загрузилась автоматически, впишите её ID вручную.
- Нажмите Verify или сохраните настройки, затем отправьте тест в режиме Ask.

## Параметры модели

Cline позволяет вручную указать размер контекста, максимальный ответ, поддержку изображений и цены. Эти поля описывают возможности клиента, но не расширяют возможности самой модели. Не включайте изображения или computer use, если выбранная модель их не поддерживает.

## Если Cline не отвечает

- 401: заново скопируйте ключ и проверьте его статус.
- Model Not Found: используйте точный ID из каталога Elysium AI.
- Connection Error: проверьте, что Base URL заканчивается на один /v1.
- Ошибки tools: выберите модель, которая поддерживает OpenAI-совместимый tool calling.

- [Официальная справка Cline](https://docs.cline.bot/provider-config/openai-compatible): Настройка OpenAI Compatible и описание полей модели.

---

# Roo Code

Создайте отдельный OpenAI Compatible профиль Elysium AI для Roo Code.

https://elysiumai.garden/docs/integrations/roo-code

## Новый профиль

Отдельный профиль не затрагивает уже настроенных провайдеров Roo Code и позволяет быстро переключаться между ними.

[Новый профиль](https://elysiumai.garden/docs/integrations/roo-code#setup)

## Настройка в интерфейсе

- Откройте настройки Roo Code и создайте API-профиль.
- Выберите OpenAI Compatible.
- В Base URL вставьте https://elysiumai.garden/v1, затем укажите ключ и Model ID.
- Сохраните профиль и выберите его для текущей задачи.
- Первую проверку проведите в Ask, не разрешая изменение файлов.

## Почему важен tool calling

Roo Code работает с нативными OpenAI tools. Для чтения файлов, запуска команд и правок нужна модель с корректным function/tool calling. Обычный текстовый ответ ещё не подтверждает, что агентные инструменты будут работать.

> Если модель отвечает текстом вместо вызова инструмента или возвращает ошибку схемы tools, смените модель. Отключение безопасности или повторные автозапуски проблему совместимости не исправят.

## Сверка настроек

- [Официальная справка Roo Code](https://roocodeinc.github.io/Roo-Code/providers/openai-compatible/): OpenAI Compatible, native tool calling и диагностика.

---

# Kilo Code

Добавьте Elysium AI как Custom provider с OpenAI-совместимым API.

https://elysiumai.garden/docs/integrations/kilo-code

## Custom provider

Kilo Code может загрузить модели через /v1/models или принять ID вручную. Для первой настройки используйте OpenAI Compatible и Chat Completions.

[Custom provider](https://elysiumai.garden/docs/integrations/kilo-code#setup)

## Через интерфейс Kilo Code

- Откройте Settings → Providers и нажмите Custom provider.
- Задайте Provider ID elysium и отображаемое имя Elysium AI.
- В Provider API выберите OpenAI Compatible.
- Вставьте https://elysiumai.garden/v1 и API-ключ.
- Выберите загруженную модель или добавьте точный ID вручную, затем сохраните провайдера.

## Выбор протокола

Custom provider также предлагает OpenAI Responses и Anthropic Messages. Для моделей с обычным OpenAI endpoint используйте OpenAI Compatible. Responses выбирайте только для модели, у которой этот формат явно указан в каталоге.

> Название протокола определяет форму запроса. Переключение на Responses не делает Chat Completions-модель совместимой с Responses автоматически.

## Дополнительные поля

- [Официальная справка Kilo Code](https://kilo.ai/docs/code-with-ai/agents/custom-models): Custom Models, Provider API, ручные модели и конфигурация.

---

# OpenCode

Настройте постоянного OpenAI-compatible провайдера Elysium AI в opencode.json.

https://elysiumai.garden/docs/integrations/opencode

## Готовая конфигурация

OpenCode хранит описание провайдера в конфигурации, а ключ безопаснее брать из переменной окружения. Мастер добавит выбранную модель и команду для вашей системы.

[Готовая конфигурация](https://elysiumai.garden/docs/integrations/opencode#setup)

## Подключение ключа

- Запустите OpenCode и выполните /connect.
- Выберите Other и задайте уникальный provider ID elysium.
- Введите API-ключ. OpenCode сохранит credential отдельно от описания моделей.
- Создайте opencode.json в проекте или откройте существующий файл и добавьте блок из мастера.
- Перезапустите OpenCode и выберите модель через /models.

## Chat Completions или Responses

Пакет @ai-sdk/openai-compatible отправляет Chat Completions. Для Responses-only модели OpenCode рекомендует @ai-sdk/openai. Не смешивайте оба формата в одной записи модели без отдельной проверки.

## Проверка конфигурации

- opencode auth list показывает, сохранён ли credential для provider ID.
- ID в /connect должен полностью совпадать с ключом provider в opencode.json.
- Модель появится в /models только после корректного описания provider.models.
- Ключ не следует записывать обычной строкой в файл проекта.

- [Официальная справка OpenCode](https://opencode.ai/docs/providers/#custom-provider): Custom provider, /connect, npm adapter и baseURL.

---

# Zed

Добавьте OpenAI-compatible provider Elysium AI в настройки Zed Agent.

https://elysiumai.garden/docs/integrations/zed

## Настройка Zed AI

Zed умеет создавать пользовательского OpenAI-compatible провайдера через интерфейс и хранит ключ в системной связке ключей.

[Настройка Zed AI](https://elysiumai.garden/docs/integrations/zed#setup)

## Через Agent Settings

- Откройте палитру команд и выполните agent: open settings.
- В LLM Providers нажмите Add Provider и выберите OpenAI-compatible.
- Укажите имя Elysium AI, API URL, точный Model ID и размер контекста.
- Введите ключ в интерфейсе провайдера, а не в settings.json.
- Выберите добавленную модель в Agent Panel и отправьте короткий запрос.

## Ручная конфигурация

Мастер формирует блок language_models.openai_compatible. Значение max_tokens — локальное описание окна контекста для Zed; уточните лимит выбранной модели и при необходимости замените значение.

> Имя провайдера elysium-ai создаёт переменную ELYSIUM_AI_API_KEY. Если она задана в окружении процесса Zed, она имеет приоритет над ключом из системного хранилища.

## Возможности моделей

- [Официальная справка Zed](https://zed.dev/docs/ai/use-api-access#openai-compatible-endpoints): OpenAI-compatible endpoints, доступные модели и capabilities.

---

# Cursor

Используйте Elysium AI в Cursor через совместимое расширение Cline, Roo Code или Kilo Code.

https://elysiumai.garden/docs/integrations/cursor

## Рабочий способ

Cursor поддерживает расширения VS Code. Установите Cline, Roo Code или Kilo Code внутрь Cursor и настройте в нём OpenAI Compatible. Подключение относится к расширению, а не к встроенному Cursor Agent.

[Рабочий способ](https://elysiumai.garden/docs/integrations/cursor#setup)

## Подключение

- Откройте Extensions внутри Cursor.
- Установите Cline, Roo Code или Kilo Code.
- Откройте настройки API установленного расширения и выберите OpenAI Compatible.
- Укажите https://elysiumai.garden/v1, отдельный API-ключ и точный Model ID.
- Откройте панель расширения и выполните проверку в режиме Ask.

## Что именно будет работать

Такое разделение полезно: встроенный Cursor остаётся со своей конфигурацией, а профиль Elysium AI работает независимо в панели расширения.

> Модель Elysium AI появится в выбранном расширении. Она не заменит модели встроенного Cursor Agent и не появится в его системном селекторе.

## Справка

- [Настройки API в Cursor](https://cursor.com/docs): Официальная документация Cursor по поддерживаемым API-ключам.
- [Гайд Cline](https://elysiumai.garden/docs/integrations/cline): Самый прямой OpenAI-compatible вариант внутри Cursor.

---

# Qwen Code

Подключите Elysium AI как OpenAI-compatible model provider для Qwen Code.

https://elysiumai.garden/docs/integrations/qwen-code

## Model provider

Актуальная схема Qwen Code отделяет описание модели от credential: settings.json содержит envKey, а реальный ключ читается из окружения.

[Model provider](https://elysiumai.garden/docs/integrations/qwen-code#setup)

## Запуск

- Задайте ELYSIUM_API_KEY в PowerShell или терминале.
- Откройте ~/.qwen/settings.json и добавьте modelProviders из мастера.
- Перезапустите Qwen Code, чтобы он перечитал окружение и конфигурацию.
- Выполните /model и выберите добавленный ID.
- Отправьте короткий запрос без разрешения на изменение файлов.

## Одноразовый запуск

### macOS / Linux

```bash
qwen --auth-type openai   --model your-model-id   --openai-api-key "$ELYSIUM_API_KEY"   --openai-base-url "https://elysiumai.garden/v1"
```

### PowerShell

```powershell
qwen --auth-type openai --model your-model-id --openai-api-key $env:ELYSIUM_API_KEY --openai-base-url "https://elysiumai.garden/v1"
```

> CLI-флаги удобны для проверки. Для постоянной настройки используйте modelProviders и envKey.

## Приоритет настроек

- [Официальная справка Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/model-providers/): modelProviders, auth type openai, envKey и порядок разрешения параметров.

---

# OAI Compatible Copilot

Добавьте Elysium AI в Copilot Chat через расширение OAI Compatible Copilot.

https://elysiumai.garden/docs/integrations/oai-compatible-copilot

## Провайдер и модель

Расширение регистрирует пользовательские модели в интерфейсе Copilot Chat. Провайдер и модели удобнее создать через встроенную Configuration UI.

[Провайдер и модель](https://elysiumai.garden/docs/integrations/oai-compatible-copilot#setup)

## Настройка через интерфейс

- Установите OAI Compatible Copilot в VS Code.
- Откройте Command Palette и выполните OAICopilot: Open Configuration UI.
- В Provider Management добавьте elysium с API mode openai, Base URL и ключом.
- В Model Management создайте модель с точным ID из каталога и выберите созданного провайдера.
- Откройте Copilot Chat, Manage Models и включите модель OAI Compatible.

## Перед установкой

Создайте отдельный ключ с небольшим бюджетом. Если расширение больше не используется, отключите ключ в кабинете.

> Это стороннее community-расширение, а не функция GitHub Copilot или Elysium AI. Проверьте издателя, разрешения и репозиторий перед тем, как передавать расширению API-ключ.

## Конфигурация моделей

- [Репозиторий OAI Compatible Copilot](https://github.com/JohnnyZ93/oai-compatible-copilot): Configuration UI, API modes, model fields и команды расширения.

---

# Codex

Настройте Elysium AI как custom model provider для Codex CLI.

https://elysiumai.garden/docs/integrations/codex

## 1. Передайте ключ

### macOS / Linux

```bash
export ELYSIUM_API_KEY="sk-..."
```

### PowerShell

```powershell
$env:ELYSIUM_API_KEY="sk-..."
```

## 2. Настройте Codex

Откройте пользовательский файл ~/.codex/config.toml. Впишите ID модели, которая поддерживает Responses, и добавьте провайдера Elysium AI.

### ~/.codex/config.toml

```toml
model = "your-responses-model-id"
model_provider = "elysium"

[model_providers.elysium]
name = "Elysium AI"
base_url = "https://elysiumai.garden/v1"
env_key = "ELYSIUM_API_KEY"
wire_api = "responses"
```

## 3. Запустите

### Terminal

```bash
codex
# или короткая проверка
codex exec "Ответь одним словом: работает"
```

> Не добавляйте /responses к base_url: Codex добавляет маршрут сам.

---

# Claude Code

Подключите Claude Code к Anthropic-совместимому маршруту Elysium AI.

https://elysiumai.garden/docs/integrations/claude-code

## Важное отличие адреса

Claude Code самостоятельно добавляет /v1/messages. Поэтому для него базовый адрес — https://elysiumai.garden без /v1.

> Если указать https://elysiumai.garden/v1, клиент может отправить запрос на ошибочный двойной путь /v1/v1/messages.

## Настройка текущего терминала

### macOS / Linux

```bash
export ELYSIUM_API_KEY="sk-..."
export ELYSIUM_MODEL="your-anthropic-model-id"
export ANTHROPIC_BASE_URL="https://elysiumai.garden"
export ANTHROPIC_AUTH_TOKEN="$ELYSIUM_API_KEY"
export ANTHROPIC_MODEL="$ELYSIUM_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ELYSIUM_MODEL"

claude --model "$ANTHROPIC_MODEL"
```

### PowerShell

```powershell
$env:ELYSIUM_API_KEY="sk-..."
$env:ELYSIUM_MODEL="your-anthropic-model-id"
$env:ANTHROPIC_BASE_URL="https://elysiumai.garden"
$env:ANTHROPIC_AUTH_TOKEN=$env:ELYSIUM_API_KEY
$env:ANTHROPIC_MODEL=$env:ELYSIUM_MODEL
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL=$env:ELYSIUM_MODEL

claude --model $env:ANTHROPIC_MODEL
```

## Постоянная настройка

### ~/.claude/settings.json

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://elysiumai.garden",
    "ANTHROPIC_AUTH_TOKEN": "sk-...",
    "ANTHROPIC_MODEL": "your-anthropic-model-id",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "your-anthropic-model-id"
  }
}
```

## Проверка

Запустите Claude Code из того же терминала и выполните /status. Проверьте базовый URL и выбранную модель. Ошибка 401 указывает на ключ, 404 — на URL или model ID.

---

# Лимиты и HTTP 429

Как реагировать на ограничение частоты запросов.

https://elysiumai.garden/docs/limits

## Что означает 429

Сервис временно отклонил запрос из-за превышения количества запросов в минуту. Лимит применяется к аккаунту, поэтому создание дополнительных API-ключей не увеличивает доступный RPM.

## Правильный повтор

- Не повторяйте запрос мгновенно.
- Используйте exponential backoff с небольшой случайной задержкой.
- Ограничьте количество параллельных запросов.
- Если ошибка повторяется постоянно, обратитесь к администратору за изменением RPM.

### Python

```python
import random
import time

def wait_before_retry(attempt: int):
    delay = min(30, 2 ** attempt + random.random())
    time.sleep(delay)
```

---

# Ошибки API

Формат ошибки, основные HTTP-статусы и стратегия повторов.

https://elysiumai.garden/docs/errors

## Формат ответа

Сохраняйте message, code и request ID. Request ID нужен поддержке, чтобы найти конкретный запрос.

### JSON

```json
{
  "error": {
    "message": "Модель временно недоступна. ID: req_example",
    "type": "elyziumai_error",
    "code": "server_error"
  }
}
```

## Что делать с HTTP-кодами

| HTTP | Причина | Действие |
| --- | --- | --- |
| 400 | Ошибка в JSON или параметрах | Исправить тело запроса |
| 401 | Проблема с API-ключом | Проверить Authorization и статус ключа |
| 402 | Недостаточно средств | Пополнить баланс или проверить бюджет ключа |
| 403 | Нет доступа к модели | Проверить модель и ограничения ключа |
| 404 | Маршрут или модель не найдены | Проверить URL и model ID |
| 429 | Превышен RPM | Повторить с задержкой |
| 500 | Внутренняя ошибка | Повторить позже |
| 502 / 503 / 504 | Временная недоступность | Повторить с задержкой или выбрать другую модель |

## Когда повторять

- Повторяйте 429, 500, 502, 503 и 504 с задержкой.
- Не повторяйте 400, 401, 402, 403 и 404 без изменения запроса или состояния аккаунта.
- Ограничивайте число повторов, чтобы не создавать бесконечный цикл.

---

# Решение ошибок и совместимость

Поиск по реальным API-ошибкам, проверка совместимости моделей и готовые конфигурации для IDE, SDK и no-code инструментов.

https://elysiumai.garden/docs/troubleshooting

## Найдите ошибку по её тексту

Вставьте фрагмент сообщения или выберите клиент. Поиск выполняется в браузере и не отправляет текст ошибки на сервер.

[Найдите ошибку по её тексту](https://elysiumai.garden/docs/troubleshooting#search)

## Генератор совместимой конфигурации

Выберите клиент и тип модели. Генератор покажет Base URL, рекомендуемый протокол и безопасный минимальный запрос.

[Генератор совместимой конфигурации](https://elysiumai.garden/docs/troubleshooting#configurator)

## Как мы поддерживаем новые модели

- Совместимость определяется по протоколу и возможностям модели, а не только по словам GPT, Claude, Gemini или Opus в имени.
- Для неизвестных моделей применяется консервативный профиль, после чего возможности уточняются по метаданным и ответам upstream.
- Безопасный retry допускается только для детерминированной параметрической ошибки и не должен повторять уже выполненный платный запрос.

- [Автоматическое определение будущих моделей](https://elysiumai.garden/docs/troubleshooting/future-model-capability-detection): Как добавление условного Opus 4.7 не должно требовать нового hardcode.

---

# Claude: thinking.enabled is not supported

Почему Claude отклоняет thinking.enabled и как использовать adaptive thinking без ошибки 400.

https://elysiumai.garden/docs/troubleshooting/claude-thinking-enabled-not-supported

## Текст ошибки

"thinking.enabled" is not supported for this model. Use "thinking.adaptive" and "output_config.effort"

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Клиент отправляет старый формат управления thinking в модель, которая принимает adaptive thinking. Совместимый шлюз должен нормализовать этот параметр по возможностям конкретной модели.

| Клиенты | Модели |
| --- | --- |
| Claude Desktop, Claude Code, Cursor | Claude Opus, Claude Sonnet |

## Как проверить

- Проверьте точный model ID в журнале запроса.
- Убедитесь, что клиент не дублирует thinking в extra_body.
- Повторите запрос без thinking, чтобы отделить проблему параметра от проблемы модели.

## Как исправить

- Обновите Claude Desktop или интеграцию до актуальной версии.
- Для новых Claude используйте adaptive thinking и effort.
- Если клиент невозможно обновить, удалите thinking.enabled: ElysiumAI выполнит совместимую нормализацию поддерживаемых полей.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

## Рабочий пример

### Пример

```json
{
  "model": "claude-opus",
  "messages": [{"role": "user", "content": "Проверь запрос"}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}
```

## Связанные материалы

- [Claude: model does not support the effort parameter](https://elysiumai.garden/docs/troubleshooting/claude-effort-parameter-not-supported): Как убрать effort для моделей Claude, которые не поддерживают управление глубиной рассуждений.
- [Как автоматически поддерживать новые модели](https://elysiumai.garden/docs/troubleshooting/future-model-capability-detection): Почему условный Claude Opus 4.7 должен определяться по возможностям, а не по жёсткому списку имён.

---

# Claude: model does not support the effort parameter

Как убрать effort для моделей Claude, которые не поддерживают управление глубиной рассуждений.

https://elysiumai.garden/docs/troubleshooting/claude-effort-parameter-not-supported

## Текст ошибки

This model does not support the 'effort' parameter. Please remove it from your request.

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Один клиентский профиль применяется к разным поколениям моделей. Поле effort допустимо только там, где upstream объявляет соответствующую возможность.

| Клиенты | Модели |
| --- | --- |
| Claude Desktop, Claude Code, OpenAI SDK | Claude Haiku, Claude Sonnet, Claude Opus |

## Как проверить

- Сравните ошибку с запросом без effort.
- Проверьте, не добавляет ли effort IDE автоматически.
- Убедитесь, что псевдоним модели указывает на ожидаемое поколение.

## Как исправить

- Удаляйте effort для моделей без этой возможности.
- Не привязывайте совместимость к слову opus или sonnet в имени.
- Используйте автоматическую нормализацию ElysiumAI, которая учитывает capability-профиль и ответ upstream.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

## Рабочий пример

### Пример

```json
{
  "model": "claude-sonnet",
  "messages": [{"role": "user", "content": "Ответь кратко"}]
}
```

## Связанные материалы

- [Claude: thinking.enabled is not supported](https://elysiumai.garden/docs/troubleshooting/claude-thinking-enabled-not-supported): Почему Claude отклоняет thinking.enabled и как использовать adaptive thinking без ошибки 400.
- [Как автоматически поддерживать новые модели](https://elysiumai.garden/docs/troubleshooting/future-model-capability-detection): Почему условный Claude Opus 4.7 должен определяться по возможностям, а не по жёсткому списку имён.

---

# Как подключить Claude Desktop к совместимому API

Base URL, API key, модель и диагностика подключения Claude Desktop к ElysiumAI.

https://elysiumai.garden/docs/troubleshooting/claude-desktop-custom-api-setup

## Текст ошибки

Claude Desktop returns 400, 401 or model not found after adding a custom provider

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Чаще всего клиенту передают URL без нужного API-префикса, неверный ключ или model ID, отсутствующий в каталоге.

| Клиенты | Модели |
| --- | --- |
| Claude Desktop | Claude Opus, Claude Sonnet, Claude Haiku |

## Как проверить

- Откройте /v1/models тем же ключом.
- Скопируйте model ID из каталога без изменения регистра.
- Проверьте, какой протокол ожидает конкретная сборка Claude Desktop.

## Как исправить

- Используйте генератор конфигурации ниже.
- Для OpenAI-compatible режима укажите https://elysiumai.garden/v1.
- Не вставляйте /chat/completions в поле Base URL.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

## Связанные материалы

- [401 Invalid API key](https://elysiumai.garden/docs/troubleshooting/invalid-api-key-401): Полная проверка Bearer-заголовка, статуса ключа и неправильного Base URL.
- [404 Model not found](https://elysiumai.garden/docs/troubleshooting/model-not-found-404): Как проверить точный model ID, доступ ключа и устаревший alias.
- [400 Unknown or unsupported parameter](https://elysiumai.garden/docs/troubleshooting/unknown-parameter-400): Универсальная диагностика несовместимого поля без удаления полезных возможностей запроса.

---

# Anthropic API: отсутствует anthropic-version

Что делать с ошибкой обязательного заголовка anthropic-version в Anthropic-compatible запросах.

https://elysiumai.garden/docs/troubleshooting/anthropic-version-header-missing

## Текст ошибки

anthropic-version header is required

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Нативный Anthropic Messages API требует версию протокола, а OpenAI-compatible endpoint использует другой набор заголовков.

| Клиенты | Модели |
| --- | --- |
| Claude Code, cURL, Python SDK | Claude |

## Как проверить

- Определите, используете ли вы /anthropic/v1/messages или /v1/chat/completions.
- Не смешивайте x-api-key и Bearer-схемы из разных протоколов.
- Проверьте заголовки через безопасный request dump без ключа.

## Как исправить

- Добавьте anthropic-version для нативного Anthropic endpoint.
- Либо переключите клиент на OpenAI-compatible endpoint и его формат.
- Используйте один протокол на весь запрос.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

## Рабочий пример

### Пример

```bash
curl https://elysiumai.garden/anthropic/v1/messages \
  -H "x-api-key: sk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json"
```

---

# max_tokens или max_completion_tokens

Как выбрать правильный лимит ответа для GPT, reasoning-моделей и OpenAI-compatible API.

https://elysiumai.garden/docs/troubleshooting/openai-max-tokens-vs-max-completion-tokens

## Текст ошибки

Unsupported parameter: max_tokens

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Новые reasoning-модели могут принимать max_completion_tokens или max_output_tokens вместо старого max_tokens.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, Codex, Cursor | GPT, o-series, Reasoning models |

## Как проверить

- Уточните endpoint: Chat Completions или Responses.
- Проверьте документацию выбранной модели.
- Удалите все лимиты и повторите минимальный запрос.

## Как исправить

- Для Chat Completions reasoning-моделей используйте max_completion_tokens.
- Для Responses API используйте max_output_tokens.
- Не отправляйте несколько эквивалентных лимитов одновременно.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Role developer is not supported

Почему некоторые модели не принимают роль developer и когда заменять её на system.

https://elysiumai.garden/docs/troubleshooting/openai-developer-role-not-supported

## Текст ошибки

Unsupported value: 'developer'. Supported values are: 'system', 'assistant', 'user'

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Клиент использует новую семантику ролей с моделью или upstream, поддерживающими только старый набор.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, Codex, LangChain | GPT, Legacy chat models |

## Как проверить

- Найдите сообщение с role=developer.
- Проверьте endpoint и фактический upstream.
- Повторите запрос с ролью system.

## Как исправить

- Для старой модели замените developer на system.
- Для новых моделей оставляйте developer, если это указано в capability-профиле.
- Не преобразовывайте tool и assistant сообщения в system.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# response_format json_schema не поддерживается

Диагностика Structured Outputs и безопасный fallback на json_object или обычный текст.

https://elysiumai.garden/docs/troubleshooting/openai-json-schema-response-format

## Текст ошибки

response_format.type json_schema is not supported

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Клиент запросил строгую JSON-схему у модели, которая поддерживает только JSON mode или вообще не гарантирует JSON.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, LangChain, n8n | GPT, DeepSeek, Qwen |

## Как проверить

- Проверьте поддержку Structured Outputs у model ID.
- Упростите schema и уберите strict.
- Проверьте минимальный запрос с json_object.

## Как исправить

- Используйте json_schema только для моделей с соответствующей возможностью.
- Сделайте fallback на json_object.
- Валидируйте ответ в приложении и повторяйте запрос при нарушении схемы.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# parallel_tool_calls is not supported

Как исправить ошибку parallel_tool_calls в агентских клиентах и моделях без параллельных tools.

https://elysiumai.garden/docs/troubleshooting/openai-parallel-tool-calls-unsupported

## Текст ошибки

This model does not support the 'parallel_tool_calls' parameter

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

IDE или агент всегда отправляет управление параллельными tools, хотя выбранная модель не поддерживает поле.

| Клиенты | Модели |
| --- | --- |
| Codex, Cursor, LangChain | GPT, Claude, Open models |

## Как проверить

- Повторите запрос без tools.
- Затем добавьте одну функцию без parallel_tool_calls.
- Проверьте capability-профиль модели.

## Как исправить

- Удалите parallel_tool_calls для неподдерживаемых моделей.
- Не отключайте сами tools, если модель поддерживает function calling.
- Включайте параметр только по capability-флагу.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# stream_options.include_usage вызывает 400

Почему upstream не принимает usage в SSE-потоке и как сохранить streaming.

https://elysiumai.garden/docs/troubleshooting/openai-stream-include-usage-unsupported

## Текст ошибки

Unknown parameter: stream_options

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Некоторые совместимые провайдеры реализуют SSE, но не дополнительный usage chunk.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, Cursor, Open WebUI | OpenAI-compatible models |

## Как проверить

- Проверьте обычный non-stream запрос.
- Проверьте stream=true без stream_options.
- Убедитесь, что клиент не требует финальный usage chunk.

## Как исправить

- Удалите stream_options, сохранив stream=true.
- Получайте usage из биллингового журнала.
- Добавляйте include_usage только для подтверждённых моделей.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Codex и Responses API через совместимый шлюз

Настройка Codex для моделей с Responses API и диагностика несовместимого endpoint.

https://elysiumai.garden/docs/troubleshooting/codex-responses-api-setup

## Текст ошибки

Codex sends Responses API fields to a Chat Completions-only model

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Codex использует Responses API и инструменты, а выбранный маршрут или модель реализуют только Chat Completions.

| Клиенты | Модели |
| --- | --- |
| Codex | GPT, Reasoning models |

## Как проверить

- Проверьте поддержку /v1/responses.
- Отправьте минимальный input без tools.
- Проверьте model ID через /v1/models.

## Как исправить

- Выберите модель с поддержкой Responses API.
- Используйте Base URL без добавления endpoint вручную.
- Для Chat-only модели используйте клиент, умеющий Chat Completions.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Gemini: invalid system_instruction

Как передавать системную инструкцию в Gemini-compatible и OpenAI-compatible режимах.

https://elysiumai.garden/docs/troubleshooting/gemini-system-instruction-invalid

## Текст ошибки

Invalid JSON payload received. Unknown name system_instruction

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

В запросе смешаны поля OpenAI и нативного Gemini GenerateContent API.

| Клиенты | Модели |
| --- | --- |
| Gemini CLI, Google GenAI SDK, OpenAI SDK | Gemini |

## Как проверить

- Определите активный endpoint.
- Сравните структуру contents/messages.
- Удалите system_instruction и проверьте базовый запрос.

## Как исправить

- В нативном Gemini формате используйте systemInstruction ожидаемой структуры.
- В OpenAI-compatible формате используйте system/developer message.
- Не отправляйте оба варианта одновременно.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Gemini safetySettings: неверный формат

Исправление категорий и порогов safetySettings без смешивания форматов SDK.

https://elysiumai.garden/docs/troubleshooting/gemini-safety-settings-format

## Текст ошибки

Invalid value at safetySettings or unknown enum value

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Названия полей и enum отличаются между версиями Gemini API и SDK.

| Клиенты | Модели |
| --- | --- |
| Gemini CLI, Google GenAI SDK | Gemini |

## Как проверить

- Зафиксируйте версию используемого SDK.
- Проверьте регистр category и threshold.
- Повторите запрос без safetySettings.

## Как исправить

- Используйте структуру из той же версии API, что и endpoint.
- Не переносите camelCase-поля в snake_case API автоматически.
- Добавляйте настройки безопасности только после успешного базового запроса.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# DeepSeek Reasoner: несовместимые параметры

Какие chat-параметры часто отклоняет reasoning-модель DeepSeek и как построить fallback.

https://elysiumai.garden/docs/troubleshooting/deepseek-reasoner-unsupported-parameters

## Текст ошибки

Unsupported parameter for reasoning model

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Обычный chat-профиль отправляет temperature, top_p, logprobs или другие параметры, которые reasoning-вариант не использует.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, Cursor, n8n | DeepSeek Reasoner |

## Как проверить

- Сведите тело к model и messages.
- Добавляйте поля по одному.
- Проверьте фактический ID reasoning-модели.

## Как исправить

- Удаляйте sampling-параметры, запрещённые моделью.
- Храните capability-профиль отдельно от семейства DeepSeek.
- Не копируйте настройки обычной chat-модели в reasoner.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Grok: параметры live search не поддерживаются

Как отличить встроенный web search Grok от tool calling и не получить unknown parameter.

https://elysiumai.garden/docs/troubleshooting/grok-search-parameters-unsupported

## Текст ошибки

Unknown parameter related to search or sources

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Клиент использует параметры из другой версии xAI API или пытается передать встроенный search через OpenAI tools.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, LangChain | Grok |

## Как проверить

- Проверьте версию endpoint.
- Запустите запрос без search.
- Проверьте, возвращает ли выбранная модель citations.

## Как исправить

- Используйте поля поиска, поддерживаемые конкретным upstream.
- Не смешивайте provider-native search и function tools.
- При отсутствии встроенного поиска вызывайте внешний search tool на стороне приложения.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Qwen enable_thinking: совместимость клиентов

Как включать thinking у Qwen без передачи vendor-поля неподдерживаемым моделям.

https://elysiumai.garden/docs/troubleshooting/qwen-enable-thinking-compatibility

## Текст ошибки

Unknown parameter: enable_thinking

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Vendor-параметр Qwen передаётся через общий профиль всем моделям или не в том уровне JSON.

| Клиенты | Модели |
| --- | --- |
| Qwen Code, OpenAI SDK, Cursor | Qwen |

## Как проверить

- Проверьте документацию конкретного Qwen endpoint.
- Повторите запрос без enable_thinking.
- Проверьте extra_body в SDK.

## Как исправить

- Передавайте enable_thinking только Qwen-моделям, где он заявлен.
- Используйте extra_body, если SDK не знает поле.
- Для других моделей преобразуйте намерение в их собственный параметр или удалите поле.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Kimi: context length exceeded

Как посчитать реальный контекст Kimi с system prompt, tools и ожидаемым ответом.

https://elysiumai.garden/docs/troubleshooting/kimi-context-length-exceeded

## Текст ошибки

This model's maximum context length is exceeded

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

К лимиту относятся не только видимые сообщения, но и system prompt, описания tools, изображения и резерв под ответ.

| Клиенты | Модели |
| --- | --- |
| Cursor, Open WebUI, OpenAI SDK | Kimi |

## Как проверить

- Сравните prompt_tokens в журнале.
- Отключите tools и повторите запрос.
- Уменьшите max_tokens и историю.

## Как исправить

- Обрезайте старые сообщения или делайте summary.
- Сократите JSON Schema инструментов.
- Оставляйте запас под completion и служебные токены.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Как автоматически поддерживать новые модели

Почему условный Claude Opus 4.7 должен определяться по возможностям, а не по жёсткому списку имён.

https://elysiumai.garden/docs/troubleshooting/future-model-capability-detection

## Текст ошибки

A newly added model rejects a parameter inherited from a model-name rule

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Жёсткие проверки по названию быстро устаревают. Надёжная схема сочетает явные capability-метаданные, семейство протокола и безопасный retry после параметрической ошибки.

| Клиенты | Модели |
| --- | --- |
| Любой клиент | Новые и неизвестные модели |

## Как проверить

- Проверьте метаданные канала и модели.
- Посмотрите, какие параметры реально отклонил upstream.
- Убедитесь, что fallback не повторяет платный успешный запрос.

## Как исправить

- Сначала используйте явные capabilities модели.
- Для неизвестной модели применяйте консервативный профиль протокола.
- При детерминированной 400-ошибке удаляйте только названный несовместимый параметр и выполняйте один безопасный retry.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

## Связанные материалы

- [400 Unknown or unsupported parameter](https://elysiumai.garden/docs/troubleshooting/unknown-parameter-400): Универсальная диагностика несовместимого поля без удаления полезных возможностей запроса.
- [Claude: thinking.enabled is not supported](https://elysiumai.garden/docs/troubleshooting/claude-thinking-enabled-not-supported): Почему Claude отклоняет thinking.enabled и как использовать adaptive thinking без ошибки 400.

---

# Cursor: model not found с custom API

Диагностика model ID, Base URL и собственного провайдера в Cursor.

https://elysiumai.garden/docs/troubleshooting/cursor-custom-api-model-not-found

## Текст ошибки

The model does not exist or you do not have access to it

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Cursor отправляет отображаемое имя вместо точного model ID либо обращается к другому Base URL.

| Клиенты | Модели |
| --- | --- |
| Cursor | Любые |

## Как проверить

- Скопируйте ID из /v1/models.
- Проверьте, не добавляет ли Cursor префикс провайдера.
- Сопоставьте request ID с серверным журналом.

## Как исправить

- Используйте точный ID из каталога.
- Укажите https://elysiumai.garden/v1 как Base URL.
- Создайте отдельный профиль для моделей с другим протоколом.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Windsurf, Zed и JetBrains: настройка API

Единый чек-лист custom OpenAI provider для IDE и диагностика различий Base URL.

https://elysiumai.garden/docs/troubleshooting/windsurf-zed-jetbrains-api-setup

## Текст ошибки

IDE cannot connect, lists no models or receives 404

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

IDE по-разному трактуют Base URL: одни сами добавляют /v1, другие ожидают его в настройке.

| Клиенты | Модели |
| --- | --- |
| Windsurf, Zed, JetBrains | OpenAI-compatible models |

## Как проверить

- Посмотрите итоговый URL в сетевом логе IDE.
- Проверьте GET /v1/models.
- Выполните тот же запрос через curl.

## Как исправить

- Начните с https://elysiumai.garden/v1.
- Если видите /v1/v1, уберите суффикс из настройки.
- Не используйте URL страницы документации или Dashboard.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Генерация изображений: неверный endpoint

Когда использовать /v1/images/generations, Chat Completions или vendor endpoint.

https://elysiumai.garden/docs/troubleshooting/image-generation-wrong-endpoint

## Текст ошибки

Model does not support this endpoint

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Модель изображений вызвана через текстовый endpoint или наоборот; разные провайдеры возвращают URL, base64 или async task.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, n8n, Dify | Image generation models |

## Как проверить

- Проверьте тип модели в каталоге.
- Сравните endpoint с карточкой модели.
- Проверьте обязательные size и response_format.

## Как исправить

- Для OpenAI-compatible image models используйте /v1/images/generations.
- Для мультимодального chat-редактирования следуйте карточке модели.
- Для async video/image API обрабатывайте task ID и polling.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Audio: input format is not supported

Форматы multipart, MIME type и ограничения speech-to-text и text-to-speech.

https://elysiumai.garden/docs/troubleshooting/audio-input-format-not-supported

## Текст ошибки

Invalid file format or unsupported audio format

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Файл передан как JSON/base64 вместо multipart либо его расширение не соответствует фактическому MIME type.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, n8n | Speech-to-text, Text-to-speech |

## Как проверить

- Проверьте Content-Type запроса.
- Откройте файл локальным декодером.
- Попробуйте короткий mp3 или wav без метаданных.

## Как исправить

- Для transcription используйте multipart/form-data.
- Передавайте поддерживаемый MIME type и неповреждённый файл.
- Для TTS отправляйте JSON, а бинарный ответ сохраняйте без преобразования в текст.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Видео API: где искать результат

Как отличить синхронный videos[].url от async task, polling и временного URL.

https://elysiumai.garden/docs/troubleshooting/video-generation-task-polling

## Текст ошибки

Response has no expected video URL

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Формат зависит от модели: Gemini Omni Flash через /v1/video/generations возвращает готовый videos[].url синхронно, а асинхронные модели сначала возвращают task ID.

| Клиенты | Модели |
| --- | --- |
| n8n, Python, JavaScript | Gemini Omni Flash, Video generation models |

## Как проверить

- Для google/gemini-omni-flash-preview ищите videos[0].url в исходном ответе.
- Если ответ содержит task ID, используйте status endpoint из документации выбранной модели.
- Проверьте, что вызван endpoint с карточки модели, а таймаут клиента не оборвал долгий запрос.

## Как исправить

- Для Omni не запускайте polling: дождитесь исходного POST с таймаутом не меньше 120 секунд.
- Для async-моделей опрашивайте status с ограниченным backoff и обрабатывайте queued, processing, succeeded и failed.
- Скачайте MP4 до истечения временного URL.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Embeddings: dimensions is not supported

Почему размерность embedding нельзя произвольно менять для любой модели.

https://elysiumai.garden/docs/troubleshooting/embeddings-dimensions-unsupported

## Текст ошибки

This model does not support the dimensions parameter

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Поле dimensions поддерживается только частью embedding-моделей; индекс в vector DB также должен иметь совпадающий размер.

| Клиенты | Модели |
| --- | --- |
| OpenAI SDK, LangChain, Dify | Embedding models |

## Как проверить

- Удалите dimensions и измерьте длину вектора.
- Проверьте размерность коллекции vector DB.
- Убедитесь, что вызывается /v1/embeddings.

## Как исправить

- Не отправляйте dimensions неподдерживаемой модели.
- Создайте новую коллекцию при смене размерности.
- Не смешивайте векторы разных моделей в одном индексе.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Rerank: endpoint not found

Почему rerank не является embeddings и как настроить маршрут в RAG-инструментах.

https://elysiumai.garden/docs/troubleshooting/rerank-endpoint-not-found

## Текст ошибки

404 on /v1/rerank or model does not support embeddings

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Клиент предполагает Cohere-compatible rerank endpoint, а провайдер экспонирует другой маршрут или только embeddings.

| Клиенты | Модели |
| --- | --- |
| Dify, LangChain, Open WebUI | Rerank models |

## Как проверить

- Проверьте endpoints модели в каталоге.
- Не вызывайте reranker через /v1/embeddings.
- Проверьте формат query/documents.

## Как исправить

- Настройте отдельный rerank provider.
- При отсутствии rerank endpoint используйте embedding similarity как fallback.
- Сохраняйте исходный порядок документов для корректного сопоставления score.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# LangChain: неверный openai_api_base

Настройка base_url в новых и старых пакетах LangChain без двойного /v1.

https://elysiumai.garden/docs/troubleshooting/langchain-openai-base-url

## Текст ошибки

404 Not Found or connection error after configuring LangChain

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

В разных версиях пакета используются base_url, openai_api_base или client options; endpoint может удваиваться.

| Клиенты | Модели |
| --- | --- |
| LangChain Python, LangChain JS | OpenAI-compatible models |

## Как проверить

- Проверьте версии langchain и integration package.
- Выведите итоговый URL без ключа.
- Проверьте соединение чистым OpenAI SDK.

## Как исправить

- Используйте параметр, соответствующий установленной версии.
- Задайте https://elysiumai.garden/v1 один раз.
- Зафиксируйте версии зависимостей в lock-файле.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# n8n OpenAI node возвращает 401

Проверка credentials, Base URL и заголовка Authorization в n8n.

https://elysiumai.garden/docs/troubleshooting/n8n-openai-401

## Текст ошибки

401 Incorrect API key provided

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Credential привязан не к тому node, ключ содержит пробел или n8n отправляет запрос на стандартный OpenAI URL.

| Клиенты | Модели |
| --- | --- |
| n8n | OpenAI-compatible models |

## Как проверить

- Откройте credential, используемый именно этим node.
- Создайте новый ключ без лишних пробелов.
- Проверьте Base URL в credential и operation.

## Как исправить

- Укажите ElysiumAI Base URL в custom credential.
- Не добавляйте слово Bearer в поле ключа, если node делает это сам.
- Пересохраните workflow после смены credential.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Dify не проходит проверку custom provider

Как подобрать schema, model type и endpoint для LLM, embeddings и rerank в Dify.

https://elysiumai.garden/docs/troubleshooting/dify-custom-provider-model-validation

## Текст ошибки

Credentials validation failed

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Dify валидирует не только ключ, но и тип модели отдельным тестовым запросом. Chat ID в поле embeddings закономерно не проходит.

| Клиенты | Модели |
| --- | --- |
| Dify | Chat, Embeddings, Rerank |

## Как проверить

- Выберите правильный provider type.
- Проверьте model ID и endpoint отдельно.
- Посмотрите тело validation request в серверном журнале.

## Как исправить

- Создайте отдельные credentials для LLM, embeddings и rerank.
- Укажите точный model ID из каталога.
- Не используйте chat-модель как embedding provider.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# Open WebUI не показывает модели

Диагностика /v1/models, Docker network и OpenAI API connections в Open WebUI.

https://elysiumai.garden/docs/troubleshooting/open-webui-no-models

## Текст ошибки

No models found

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Контейнер Open WebUI не может достучаться до Base URL, либо ключ не имеет доступа к каталогу.

| Клиенты | Модели |
| --- | --- |
| Open WebUI | OpenAI-compatible models |

## Как проверить

- Выполните curl /v1/models из контейнера.
- Не используйте localhost для сервиса на другом хосте.
- Проверьте ключ и фильтры моделей.

## Как исправить

- Укажите публичный https://elysiumai.garden/v1 или доступное сетевое имя.
- Перезапустите connection после изменения.
- Проверьте, что UI не скрывает модели собственным allowlist.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# 401 Invalid API key

Полная проверка Bearer-заголовка, статуса ключа и неправильного Base URL.

https://elysiumai.garden/docs/troubleshooting/invalid-api-key-401

## Текст ошибки

401 Unauthorized or Incorrect API key provided

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Запрос не содержит рабочий ключ ElysiumAI, ключ отключён либо отправляется на другой сервис.

| Клиенты | Модели |
| --- | --- |
| Любой клиент | Любые |

## Как проверить

- Проверьте Authorization: Bearer sk-... без кавычек.
- Создайте отдельный тестовый ключ.
- Выполните GET /v1/models тем же ключом.

## Как исправить

- Не вставляйте Bearer в поле, где SDK добавляет его сам.
- Удалите пробелы и переносы из секрета.
- Никогда не присылайте полный ключ в поддержку; достаточно префикса и request ID.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# 404 Model not found

Как проверить точный model ID, доступ ключа и устаревший alias.

https://elysiumai.garden/docs/troubleshooting/model-not-found-404

## Текст ошибки

The model does not exist or you do not have access to it

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

ID отсутствует в текущем каталоге, введён с ошибкой или скрыт ограничениями API-ключа.

| Клиенты | Модели |
| --- | --- |
| Любой клиент | Любые |

## Как проверить

- Получите актуальный /v1/models.
- Сравните model посимвольно.
- Проверьте ограничения ключа в Dashboard.

## Как исправить

- Скопируйте ID из каталога.
- Обновите сохранённый alias в IDE.
- Выберите доступную модель того же класса.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# 400 Unknown or unsupported parameter

Универсальная диагностика несовместимого поля без удаления полезных возможностей запроса.

https://elysiumai.garden/docs/troubleshooting/unknown-parameter-400

## Текст ошибки

Unknown parameter, unsupported parameter or extra fields not permitted

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Клиент отправляет поле из другого протокола, другой версии API или capability-профиля модели.

| Клиенты | Модели |
| --- | --- |
| Любой клиент | Любые |

## Как проверить

- Сохраните точное имя поля из ошибки.
- Повторите минимальный запрос.
- Добавляйте опции обратно по одной.

## Как исправить

- Удаляйте только названное неподдерживаемое поле.
- Не делайте бесконечные автоматические retry.
- Храните совместимость как данные по model capabilities, а не как список строковых исключений.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

## Связанные материалы

- [Как автоматически поддерживать новые модели](https://elysiumai.garden/docs/troubleshooting/future-model-capability-detection): Почему условный Claude Opus 4.7 должен определяться по возможностям, а не по жёсткому списку имён.

---

# 429 Rate limit: правильный retry

Exponential backoff, jitter и различие RPM, TPM и лимита параллельности.

https://elysiumai.garden/docs/troubleshooting/rate-limit-429-retry

## Текст ошибки

429 Too Many Requests

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Превышен лимит запросов, токенов или одновременных соединений; немедленный повтор усиливает перегрузку.

| Клиенты | Модели |
| --- | --- |
| Python SDK, JavaScript SDK, IDE | Любые |

## Как проверить

- Сохраните response headers и request ID.
- Определите RPM, TPM или concurrency.
- Проверьте, не повторяют ли запрос одновременно SDK и ваше приложение.

## Как исправить

- Используйте bounded exponential backoff с jitter.
- Ограничьте локальную конкурентность.
- Не повторяйте 400/401/402 тем же механизмом.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.

---

# SSE stream: JSON parse error

Почему нельзя парсить весь streaming response как один JSON и как обрабатывать data chunks.

https://elysiumai.garden/docs/troubleshooting/sse-stream-parsing-error

## Текст ошибки

Unexpected token 'd', "data: ..." is not valid JSON

> Не публикуйте API-ключ, полный request body с секретами или персональные данные. Для поддержки сохраните request ID и время запроса.

## Почему это происходит

Ответ text/event-stream разбирается как application/json или chunks склеиваются без учёта границ событий.

| Клиенты | Модели |
| --- | --- |
| JavaScript, Python, IDE | Streaming models |

## Как проверить

- Проверьте Content-Type.
- Отключите stream и сравните ответ.
- Посмотрите сырые строки data: без преобразования.

## Как исправить

- Используйте SSE parser или официальный SDK.
- Парсите JSON только после удаления data: для каждого события.
- Корректно завершайте поток по [DONE] или финальному событию протокола.

> После исправления сначала отправьте короткий тестовый запрос. Затем верните tools, streaming и дополнительные параметры по одному.