> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Набор инструментов для разработчиков ИИ

> Передайте интеграцию APIYI ИИ: чат-агенты устанавливают навык, терминал получает CLI, а агенты для программирования изучают контракт и реестр моделей перед написанием кода. Для каждого пути предусмотрен промпт, который можно скопировать.

<Note>
  Аккаунт и ключ по-прежнему должны быть созданы вами в [консоли](https://api.apiyi.com/token). Всё — от «у меня есть ключ» до «код работает» — можно делегировать ИИ одним из трёх способов ниже.
</Note>

## Выберите путь

<CardGroup cols={3}>
  <Card title="Навыки · чат-агенты" icon="sparkles" href="#skills">
    OpenClaw, Claude Code и другие агенты с системой навыков. Установите навык один раз, затем вызывайте APIYI на естественном языке.
  </Card>

  <Card title="CLI · терминал" icon="terminal" href="#cli">
    Без кода. Проверьте ключ, просмотрите список моделей, отправьте сообщение и сгенерируйте изображение из терминала. `npx apiyi@latest check` не требует установки.
  </Card>

  <Card title="Комплект разработчика · агенты для программирования" icon="code" href="#rules-for-coding-agents">
    Cursor, Claude Code и Codex читают контракт и реестр моделей перед написанием кода интеграции. Никаких выдуманных эндпоинтов.
  </Card>
</CardGroup>

## Что входит в комплект

Все файлы общедоступны. Авторизация не требуется, и любой агент может напрямую получить к ним доступ:

| Файл                                 | URL                                          | Назначение                                                                                                                                                                                                                   |
| ------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Контракт интеграции**              | `https://docs.apiyi.com/skill.md`            | Таблица эндпоинтов, аутентификация, правила именования моделей, известные проблемы, статусы самопроверки, контрольный список верификации. Это одновременно свод правил для агентов, выполняющих кодирование, и основа навыка |
| **Реестр моделей**                   | `https://docs.apiyi.com/model-registry.json` | Машиночитаемый источник достоверных данных об идентификаторах моделей, эндпоинтах, группах, типе тарификации и указанных ценах. Повторно генерируется вместе с таблицей цен                                                  |
| **Индекс страниц**                   | `https://docs.apiyi.com/llms.txt`            | Общесайтовый индекс, позволяющий агенту определить, какую страницу прочитать                                                                                                                                                 |
| **Полный текст**                     | `https://docs.apiyi.com/llms-full.txt`       | Все страницы, объединённые в один файл. Большой объём; загружайте по мере необходимости                                                                                                                                      |
| **Отдельная страница в виде текста** | Добавьте `.md` к URL любой страницы          | Когда нужна только одна страница. Дешевле, чем HTML                                                                                                                                                                          |
| **Сервер MCP**                       | `https://docs.apiyi.com/mcp`                 | Подключите этот сайт как сервер MCP, чтобы агент мог искать актуальное содержимое                                                                                                                                            |

<Tip>
  Версия этой страницы в виде обычного текста доступна по адресу `https://docs.apiyi.com/en/developer-kit.md`.
</Tip>

## Правила для агентов, работающих с кодом

Наиболее распространённая ошибка агента, работающего с кодом, — это не плохой код. Это **написание по памяти**: выдумывание несуществующего эндпоинта, ввод `gpt-5-4-mini` вместо `gpt-5.4-mini` или добавление лишнего `/v1` к базовому URL Anthropic SDK. Этого не допустить помогут пять правил:

1. **Не выдумывайте эндпоинты, имена параметров, значения enum или структуры ответов.** Используйте только пути из таблицы эндпоинтов `skill.md`; параметры должны соответствовать официальному определению используемого протокола (OpenAI, Anthropic или Gemini).
2. **`model-registry.json` — единственный источник истины для идентификаторов моделей.** Идентификаторы используют точечные версии и чувствительны к регистру. Дефисы в URL документации — это безопасные для URL замены, а не идентификаторы моделей.
3. **Выбирайте базовый URL по SDK, а не по модели.** OpenAI SDK использует `https://api.apiyi.com/v1`; Anthropic SDK использует корневой `https://api.apiyi.com`; Google GenAI SDK использует корневой URL с параметром `api_version`, установленным в `v1beta`.
4. **Читайте ключ только из переменной окружения `APIYI_API_KEY`.** Никогда не встраивайте его в код, не добавляйте в репозиторий и не вставляйте в чат.
5. **Сначала объяснение, затем редактирование.** Попросите агента указать, какой эндпоинт, какую модель и какой тайм-аут он планирует использовать. Он должен редактировать код только после вашего подтверждения.

<Prompt description="Полный промпт для Cursor, Claude Code, Codex и других агентов, работающих с кодом. Скопируйте и вставьте без изменений." icon="code" actions={["copy"]}>
  Перед написанием любого кода полностью прочитайте [https://docs.apiyi.com/skill.md](https://docs.apiyi.com/skill.md) и
  [https://docs.apiyi.com/llms.txt](https://docs.apiyi.com/llms.txt). Вы должны соблюдать следующие правила:

  * Не выдумывайте эндпоинты, имена параметров, значения enum или структуры ответов.
    Используйте только пути, перечисленные в таблице эндпоинтов skill.md.
  * Считайте [https://docs.apiyi.com/model-registry.json](https://docs.apiyi.com/model-registry.json) единственным источником истины для
    идентификаторов моделей. Идентификаторы используют точечные версии и чувствительны к регистру (gpt-5.4-mini, а не gpt-5-4-mini).
    Никогда не вводите их по памяти.
  * Выбирайте базовый URL по SDK: OpenAI SDK использует [https://api.apiyi.com/v1](https://api.apiyi.com/v1); Anthropic SDK
    использует [https://api.apiyi.com](https://api.apiyi.com) без /v1; Google GenAI SDK использует [https://api.apiyi.com](https://api.apiyi.com)
    с параметром api\_version, установленным в v1beta.
  * Читайте ключ только из переменной окружения APIYI\_API\_KEY. Никогда не встраивайте его в код и не добавляйте в репозиторий.
  * Для подробной информации на уровне страницы найдите страницу в llms.txt и добавьте к её имени .md, чтобы прочитать её как обычный текст.

  После завершения чтения сначала объясните своими словами планируемый процесс интеграции (какой эндпоинт, какая модель и какой тайм-аут). Пока не редактируйте код.
  Дождитесь моего подтверждения.
</Prompt>

<Accordion title="От чего защищает этот промпт">
  | Требование                          | Блокируемая ошибка                                                                                                       |
  | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
  | Никаких выдуманных эндпоинтов       | Агент собирает `/v1/complete` или `/v1/generate` по памяти из обучающих данных и зацикливается на ошибках 404            |
  | Идентификаторы моделей из реестра   | `gpt-5-4-mini` или `minimax-m3` возвращают ошибку 404, а из сообщения об ошибке непонятно, что именно неверно            |
  | Базовый URL по SDK                  | Лишний `/v1` в Anthropic SDK превращается в `/v1/v1/messages`; отсутствие `/v1` в OpenAI SDK также приводит к ошибке 404 |
  | Ключ только из переменной окружения | Встроенный в код ключ раскрывается вместе с репозиторием; pre-commit hook этого сайта также блокирует такую публикацию   |
  | Объяснение перед редактированием    | Агент не успевает изменить десять файлов, прежде чем обнаружить, что выбрал неправильный протокол                        |
</Accordion>

## Навыки

Навык — это `skill.md`: справочник интеграции, написанный для машин. После установки агент запоминает эти правила всякий раз, когда ему нужно вызвать APIYI. Есть три способа установить его:

<Tabs>
  <Tab title="npx skills (универсальный)" icon="package">
    Для Claude Code, Cursor, Codex и любых других инструментов, поддерживающих спецификацию Agent Skills:

    ```bash theme={null}
    npx skills add https://docs.apiyi.com
    ```

    Обнаружение выполняется через `/.well-known/agent-skills/index.json` этого сайта. При этом сам `skill.md` устанавливается без скриптов; для самопроверки используйте `npx apiyi@latest check`.
  </Tab>

  <Tab title="OpenClaw" icon="bot">
    Установщик навыков OpenClaw принимает источники git и ожидает наличие `SKILL.md` в корне репозитория. Репозиторий навыка `github.com/apiyi-com/skills` имеет такую структуру и содержит скрипт самопроверки:

    ```bash theme={null}
    openclaw skills install git:apiyi-com/skills
    ```

    Или клонируйте его в рабочее пространство вручную:

    ```bash theme={null}
    git clone https://github.com/apiyi-com/skills ~/.openclaw/workspace/skills/apiyi
    ```

    После установки агент запускает `scripts/apiyi.py --check` и на основании результата проводит вас через настройку ключа.
  </Tab>

  <Tab title="Ручное копирование" icon="clipboard">
    Подходит для любого агента, который может читать файлы. Поместите содержимое `https://docs.apiyi.com/skill.md` в каталог навыков:

    | Агент       | Расположение                                           |
    | ----------- | ------------------------------------------------------ |
    | Claude Code | `.claude/skills/apiyi/SKILL.md`                        |
    | Codex CLI   | `.agents/skills/apiyi/SKILL.md`                        |
    | Cursor      | Файл правил проекта или вставьте содержимое в контекст |
    | Другие      | Включите полный текст в системный промпт               |
  </Tab>
</Tabs>

<Prompt description="Для OpenClaw, Claude Code, Cursor и других агентов, поддерживающих навыки. Скопируйте и вставьте без изменений." icon="bot" actions={["copy"]}>
  Сначала установите навык APIYI, затем используйте его для интеграции APIYI для меня.

  1. Запустите `npx skills add https://docs.apiyi.com` (имя навыка: apiyi).
     Если вы используете OpenClaw, установите `git:apiyi-com/skills` с помощью установщика навыков
     или клонируйте репозиторий в \~/.openclaw/workspace/skills/apiyi/.
     Если ни один способ не работает, полностью загрузите и прочитайте [https://docs.apiyi.com/skill.md](https://docs.apiyi.com/skill.md). Содержимое идентично.
  2. Сначала выполните самопроверку: запустите `scripts/apiyi.py --check`
     (или `npx apiyi@latest check`, если скрипт отсутствует).
     При статусе no\_key запросите у меня ключ (я скопирую его с [https://api.apiyi.com/token](https://api.apiyi.com/token)) и поместите его
     в переменную окружения APIYI\_API\_KEY. Никогда не встраивайте его в код и не добавляйте в коммиты.
  3. После того как проверка сообщит о готовности, отправьте одно сообщение «Привет» с помощью gpt-5.4-mini, покажите мне ответ
     и расскажите, что вы сможете делать для меня с этим навыком в дальнейшем.
</Prompt>

### Как ключ поступает к агенту

* **Сначала используется переменная окружения `APIYI_API_KEY`.** Навык, CLI и каждый пример в этой документации считывают её оттуда.
* **OpenClaw** хранит ключ в `skills.entries.apiyi.apiKey` в `~/.openclaw/openclaw.json` и во время выполнения передаёт его как `APIYI_API_KEY`. Именно это объявляет поле `primaryEnv` во frontmatter навыка. Структуру файла см. в разделе [Файл конфигурации OpenClaw](/ru/scenarios/agent/openclaw/config-json).
* **CLI** сохраняет его с помощью `npx apiyi@latest auth set-key` в `~/.config/apiyi/config.json` с режимом 0600.

### Статусы самопроверки

Скрипт навыка, CLI и ручной вызов curl возвращают один и тот же набор статусов:

| Статус          | Значение                     | Действие агента                                                                                                  |
| --------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `ready`         | `/v1/models` вернул 200      | Сообщает, сколько моделей доступно, и спрашивает, что нужно создать                                              |
| `no_key`        | Ключ нигде не найден         | Помогает скопировать ключ из консоли, затем повторно выполняет проверку                                          |
| `invalid_key`   | 401 или 403                  | Ключ неверен, отключён или исчерпан. Просит скопировать его ещё раз                                              |
| `network_error` | Тайм-аут, ошибка DNS или 5xx | Повторяет попытку один раз, затем предлагает `vip.apiyi.com` (за пределами материкового Китая) или `b.apiyi.com` |

<Warning>
  Обычный ключ `sk-` **не может прочитать баланс**, поэтому статуса `no_balance` не существует. Для баланса и журналов используется отдельный системный токен; см. раздел [Как просматривать журналы вызовов](/ru/faq/call-logs). Код 429 может означать как превышение лимита запросов, так и нулевой баланс. Агент не должен делать предположения — ему следует указать вам на [консоль](https://api.apiyi.com/account/profile).
</Warning>

## CLI

Выполните первый вызов из терминала без написания кода. Node 18 или новее, устанавливать ничего не нужно:

```bash theme={null}
npx apiyi@latest check
```

<Prompt description="Для любого агента, который может выполнять команды терминала, или выполните эти строки самостоятельно." icon="terminal" actions={["copy"]}>
  Помогите мне установить и запустить CLI APIYI: [https://github.com/apiyi-com/cli](https://github.com/apiyi-com/cli)
  Требования: Node 18+; выполните `npx apiyi@latest check`, устанавливать ничего не нужно;
  помогите настроить ключ API (`npx apiyi@latest auth set-key` или переменная окружения APIYI\_API\_KEY, скопированная с [https://api.apiyi.com/token](https://api.apiyi.com/token));
  затем выполните `npx apiyi@latest models --grep gpt-5` и `npx apiyi@latest chat "Hello" -m gpt-5.4-mini` и вставьте вывод.
</Prompt>

### Команды

| Команда                                             | Требуется         | Назначение                                                                                                                                           |
| --------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiyi check`                                       | ключ необязателен | Показывает источник ключа, доступность Node, возвращает ли `/v1/models` код 200, задержку и статус. Показывает баланс, если настроен системный token |
| `apiyi models [--grep text]`                        | ключ необязателен | При наличии ключа выводит модели, доступные вашему ключу через `/v1/models`; без ключа считывает общедоступный реестр                                |
| `apiyi chat "prompt" [-m model] [--stream]`         | ключ              | Отправляет один запрос Chat Completions и выводит ответ и использование token. Модель по умолчанию — `gpt-5.4-mini`                                  |
| `apiyi responses "input" [-m model] [--effort low]` | ключ              | Использует эндпоинт Responses и выводит `output_text`                                                                                                |
| `apiyi image "prompt" -m gpt-image-2 [-o file]`     | ключ              | Генерирует изображение и записывает его в локальный файл; время ожидания — 360 с                                                                     |
| `apiyi balance`                                     | системный token   | Показывает баланс (500000 единиц квоты = 1 USD)                                                                                                      |
| `apiyi auth set-key` / `show` / `clear`             | не требуется      | Сохраняет ключ со скрытым вводом; `show` маскирует его; `clear` удаляет его                                                                          |

Глобальные флаги: `--api-key`, `--node api|vip|b|cf` (выбрать узел), `--base-url`, `--timeout`, `--json` (вывод в машиночитаемом формате).

### Порядок поиска ключа

Сначала флаг `--api-key`, затем переменная окружения `APIYI_API_KEY`, затем `~/.config/apiyi/config.json`, а затем `~/.openclaw/openclaw.json` OpenClaw. Если вы уже установили навык OpenClaw, CLI повторно использует этот ключ.

### Коды завершения

Скрипты и агенты используют код завершения вместо разбора текста:

| Код | Значение                                                          |
| --- | ----------------------------------------------------------------- |
| 0   | Успешное выполнение                                               |
| 2   | `no_key`                                                          |
| 3   | `invalid_key` (401 / 403)                                         |
| 4   | `network_error` (DNS, тайм-аут или 5xx после повтора)             |
| 5   | Модель не найдена (404, обычно из-за опечатки в ID)               |
| 6   | Превышен лимит запросов или недостаточно средств на балансе (429) |
| 7   | Некорректный запрос (400, выводит `error.message` без изменений)  |
| 8   | Некорректные аргументы командной строки                           |

Исходный код находится по адресу `github.com/apiyi-com/cli`; пакет npm — `apiyi`. В документации всегда указывается `npx apiyi@latest`, поскольку `npx` кэширует старые версии.

## Поля model-registry.json

Файл регенерируется при каждом обновлении таблицы цен из тех же данных, что и страница [цен на модели](/en/models). Поля верхнего уровня:

| Поле             | Значение                                                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version` | Версия схемы, в настоящее время — 1. В рамках одной версии поля только добавляются и никогда не переименовываются                             |
| `generated_at`   | Время генерации (UTC)                                                                                                                         |
| `base_urls`      | Базовый URL для каждого из трёх SDK, а также Gemini `api_version`                                                                             |
| `nodes`          | Доступные имена узлов                                                                                                                         |
| `endpoints`      | Сопоставление имени эндпоинта с путём и методом: `chat` / `responses` / `messages` / `gemini` / `images` / `embeddings` / `rerank` / `models` |
| `groups`         | Сопоставление имени группы с отображаемой меткой и коэффициентом                                                                              |
| `models[]`       | См. ниже                                                                                                                                      |

Каждая запись о модели:

| Поле                                                                    | Значение                                                                                         |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `id`                                                                    | ID модели, используется в запросах без изменений, с учётом регистра                              |
| `vendor_en`                                                             | Название поставщика на английском языке                                                          |
| `category`                                                              | Тип возможностей, например `text`, `image`, `video`, `embedding`                                 |
| `endpoints`                                                             | Имена эндпоинтов, которые принимает эта модель; соответствуют ключам верхнего уровня `endpoints` |
| `groups`                                                                | Группы tokens, которым доступен вызов этой модели                                                |
| `billing.type`                                                          | `per_token` (за миллион tokens) или `per_call`                                                   |
| `billing.input_usd_per_m` / `output_usd_per_m` / `cache_read_usd_per_m` | Публичные цены в USD для моделей с оплатой за token                                              |
| `billing.per_call_usd`                                                  | Публичная цена в USD за один вызов для моделей с оплатой за вызов                                |
| `billing.tiered`                                                        | Применяется ли многоуровневая тарификация (если значение равно true, см. страницу модели)        |
| `docs_url`                                                              | URL страницы с подробностями, если такая страница существует                                     |

<Info>
  Цены в реестре являются **публичными ценами**. Они не включают бонусы за пополнение и скидки для групп; фактические списания соответствуют данным в консоли. Описание групп приведено на странице [Описание групп](/ru/faq/groups-explained).
</Info>

## Связанные страницы

<CardGroup cols={2}>
  <Card title="Начало работы" icon="rocket" href="/ru/getting-started">
    Два пути: поручить интеграцию ИИ или выполнить её самостоятельно.
  </Card>

  <Card title="Возможна ли интеграция в один клик?" icon="plug" href="/ru/faq/one-click-integration">
    Да, в виде передачи документации ИИ, а не нажатия кнопки.
  </Card>

  <Card title="OpenClaw" icon="bot" href="/ru/scenarios/agent/openclaw/overview">
    Локальный ИИ-помощник с открытым исходным кодом; после установки навыка он обращается к APIYI на естественном языке.
  </Card>

  <Card title="Цены на модели" icon="circle-dollar-sign" href="/en/models">
    Версия реестра, удобная для чтения, с группировкой по поставщикам и ценами по уровням.
  </Card>
</CardGroup>