Как подключить нейросеть к своему приложению через API: инструкция для разработчика

Что такое API нейросети

API (программный интерфейс) — способ обращаться к модели из кода. Вы отправляете на сервер запрос со списком сообщений и названием модели, а в ответ получаете текст. Фактическим стандартом стал формат OpenAI Chat Completions: его поддерживают официальные библиотеки для Python и JavaScript и большинство сторонних инструментов.

Проблема для разработчиков из России в том, что прямой доступ к API OpenAI, Anthropic и Google требует зарубежной карты и юрлица в поддерживаемой стране. Решение — шлюз, который принимает запросы в формате OpenAI и перенаправляет их к нужной модели, а оплату берёт в рублях.

Шаг 1. Получите ключ

В NEO API ключ создаётся в личном кабинете в разделе для разработчиков. Пополните баланс в рублях — оплата списывается за фактически обработанные токены. Ключ — это пароль к вашему балансу: храните его в переменных окружения на сервере и никогда не вставляйте в код фронтенда или мобильного приложения.

Шаг 2. Первый запрос

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

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.neocraft.org/v1",
    api_key=os.environ["NEO_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "Ты — вежливый помощник. Отвечай кратко."},
        {"role": "user", "content": "Привет! Что ты умеешь?"},
    ],
)
print(resp.choices[0].message.content)

То же самое на JavaScript с официальным пакетом openai: создайте клиент с параметрами baseURL и apiKey и вызовите client.chat.completions.create с теми же полями. Без библиотек — обычный POST-запрос на /v1/chat/completions с заголовком Authorization: Bearer и JSON-телом.

Список доступных моделей и их точные идентификаторы — в документации на api.neocraft.org и в личном кабинете. Модель меняется одной строкой: можно переключиться с DeepSeek на Claude или GPT, не трогая остальной код.

Шаг 3. Системный промпт и контекст

Поведение модели задаётся системным сообщением — первым в списке, с ролью system. В нём описывают роль, тон, ограничения и формат ответа: например, «Ты — консультант интернет-магазина. Отвечай кратко, только по информации из контекста. Если ответа нет — предложи связаться с менеджером».

Модель не помнит прошлые запросы: историю диалога нужно передавать в каждом запросе. Чтобы не платить за лишнее, ограничивайте её длину — например, последними 10–20 сообщениями или кратким резюме более ранней части.

Шаг 4. Стриминг и обработка ошибок

Для чатов включайте потоковую передачу (параметр stream: true): пользователь видит ответ по мере генерации, а не ждёт его целиком. Обязательно обрабатывайте ошибки: 401 — неверный ключ, 402 или аналогичный ответ — недостаточно средств, 429 — слишком частые запросы, 5xx — временная недоступность модели. Для 429 и 5xx делайте повтор с увеличивающейся паузой, а для критичных сценариев держите запасную модель.

Сколько это стоит

Оплата идёт за токены — фрагменты текста, примерно 3–4 символа русского текста на токен в зависимости от модели. Считаются и входящие токены (ваш промпт и история), и исходящие (ответ). Цены моделей различаются в десятки раз, поэтому архитектурное правило простое: массовые простые задачи — на быстрых и дешёвых моделях, сложные — на флагманских. Текущие цены по моделям указаны в документации и в кабинете.

Безопасность и персональные данные

• Ключ — только на сервере. Фронтенд обращается к вашему бэкенду, а бэкенд — к API.
• Ограничивайте частоту запросов от одного пользователя, чтобы никто не израсходовал ваш баланс.
• Не отправляйте в модель персональные данные без необходимости; если обрабатываете их — соблюдайте требования 152-ФЗ.
• Проверяйте ответы модели перед выполнением действий: не позволяйте ей напрямую удалять данные или проводить платежи.

Что можно построить

Бот поддержки в Telegram или на сайте, автоматический разбор заявок в CRM, генерация описаний товаров из таблицы, расшифровка и анализ звонков, внутренний поиск по документам. Если не хочется писать всё самостоятельно, NEO делает такие решения под ключ — от ИИ-агента до интеграции с вашей CRM.

Частые вопросы