YandexGPT API: как получить ключ, сделать первый запрос и посчитать токены

Чтобы обратиться к YandexGPT из кода, нужны три вещи: каталог в Yandex Cloud, сервисный аккаунт с ролью ai.languageModels.user и API-ключ этого аккаунта. Дальше один POST на https://llm.api.cloud.yandex.net/foundationModels/v1/completion, и в ответе приходит сгенерированный текст. На всю настройку уходит минут двадцать, карту привязывать на старте не нужно.

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

CheckroiПодборка курсов по YandexGPT83 курса • 29 школСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Что завести в Yandex Cloud до первого запросаСкопировано

Yandex Cloud устроен матрёшкой: аккаунт → облако → каталог → ресурсы внутри каталога. Модели живут не «где-то в интернете», а в конкретном каталоге, и его идентификатор вы будете писать в каждом запросе.

Каталог и folder_id

1. Заходите в консоль Yandex Cloud под своим Yandex ID. Если почта или Алиса у вас уже есть, аккаунт тоже есть.
2. При первом входе платформа сама создаёт облако и внутри него каталог default.
3. Открываете каталог и копируете его идентификатор, строку вида b1g4c5h7m2k9p3r6t8v0. Это и есть folder_id.

folder_id нужен дважды: в адресе модели и в заголовке запроса. Держите его под рукой, дальше он появится в каждом примере.

Сервисный аккаунт и роль

Личный Yandex ID для API не годится: под ним ключ выпустить нельзя, а IAM-токен живёт всего 12 часов. Для программы заводят сервисный аккаунт, отдельную «учётку для робота» с собственным набором прав.

1. В каталоге открываете раздел сервисных аккаунтов и создаёте новый, например gpt-bot.
2. Назначаете ему роль ai.languageModels.user, минимально достаточную, чтобы вызывать генеративные модели.
3. Если планируете работать с ассистентами и тредами, добавляете ai.assistants.editor. Для простой генерации текста она не нужна.

Роль admin на весь каталог тоже даст доступ, но это плохая привычка. Ключ, который лежит в коде или в CI, рано или поздно утекает, и разница между «утёк доступ к генерации текста» и «утёк доступ ко всей инфраструктуре» примерно как между царапиной и переломом.

API-ключ

1. Открываете созданный сервисный аккаунт и нажимаете «Создать новый ключ» → API-ключ.
2. Выбираете область действия (scope) yc.ai.models.viewer: этого хватает для вызова моделей.
3. Копируете секрет. Секрет показывается ровно один раз, потом его можно только перевыпустить.

Сразу в переменные окружения. Положите ключ и folder_id в .env или в секреты вашего хостинга, а в код передавайте через os.environ. Ключ, закоммиченный в репозиторий, это самая частая причина внезапного счёта на несколько тысяч рублей.

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

Первый запрос из curl и из PythonСкопировано

Для генерации нужен один эндпоинт и три поля в теле запроса. Проверить связку проще всего из терминала.

curl -X POST https://llm.api.cloud.yandex.net/foundationModels/v1/completion \
  -H "Authorization: Api-Key $YC_API_KEY" \
  -H "x-folder-id: $YC_FOLDER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "modelUri": "gpt://'"$YC_FOLDER_ID"'/yandexgpt/rc",
    "completionOptions": {"stream": false, "temperature": 0.3, "maxTokens": 300},
    "messages": [
      {"role": "system", "text": "Отвечай кратко, одним абзацем."},
      {"role": "user",   "text": "Объясни, что такое эмбеддинг."}
    ]
  }'

Разберём поля, потому что именно в них живут и качество, и цена:

Тот же запрос на Python, без сторонних SDK:

import os
import requests

API_KEY = os.environ["YC_API_KEY"]
FOLDER_ID = os.environ["YC_FOLDER_ID"]
URL = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"


def ask(question, system="Отвечай кратко, одним абзацем.", max_tokens=300):
    payload = {
        "modelUri": f"gpt://{FOLDER_ID}/yandexgpt/rc",
        "completionOptions": {
            "stream": False,
            "temperature": 0.3,
            "maxTokens": max_tokens,
        },
        "messages": [
            {"role": "system", "text": system},
            {"role": "user", "text": question},
        ],
    }
    headers = {
        "Authorization": f"Api-Key {API_KEY}",
        "x-folder-id": FOLDER_ID,
        "Content-Type": "application/json",
    }
    response = requests.post(URL, json=payload, headers=headers, timeout=60)
    response.raise_for_status()
    return response.json()["result"]


data = ask("Объясни, что такое эмбеддинг.")
print(data["alternatives"][0]["message"]["text"])
print(data["usage"])

В ответе приходит объект result с тремя интересными частями. В alternatives лежит сам текст и статус завершения: ALTERNATIVE_STATUS_FINAL означает, что модель договорила, а ALTERNATIVE_STATUS_TRUNCATED_FINAL значит, что ответ обрезали по вашему же maxTokens. В modelVersion лежит версия, которая реально отработала. И самое важное для кошелька, блок usage.

{
  "inputTextTokens": "412",
  "completionTokens": "168",
  "totalTokens": "580"
}

Логируйте usage с первого же дня. Это единственный честный счётчик: он показывает, сколько токенов реально ушло на вызов, а не сколько вы предполагали. Без этого лога любая оптимизация превращается в гадание.

У Яндекса есть и официальный Python-SDK, ставится он как pip install yandex-cloud-ml-sdk и убирает ручную сборку JSON. Но на этапе «понять, за что я плачу» полезнее подержать в руках сырой запрос: в нём видно каждое поле, которое влияет на счёт.

Сколько стоит YandexGPT по APIСкопировано

Тарификация посимвольная только на первый взгляд. На деле считаются токены, куски слов, на которые модель режет текст. В русском языке один токен обычно короче, чем в английском, поэтому переводить рубли в «количество символов» на глазок не стоит.

Модель	Идентификатор	Цена за 1000 токенов	Когда брать
YandexGPT 5.1 Pro	yandexgpt/rc	0,40 ₽	Сложные задачи, длинные документы, качество ответа критично
YandexGPT 5 Pro	yandexgpt-5-pro	0,80 ₽	Прошлое поколение Pro, для нового кода смысла нет
YandexGPT 5 Lite	yandexgpt-lite	0,20 ₽	Классификация, теги, короткие ответы, большие объёмы
text-search-doc	text-search-doc	0,01 ₽	Векторизация документов для поиска
text-search-query	text-search-query	0,01 ₽	Векторизация пользовательских запросов

Обратите внимание на строку с 5 Pro: предыдущее поколение стоит вдвое дороже нового флагмана. Если вы копировали пример из статьи двухлетней давности и оставили в modelUri старый идентификатор, вы платите двойной тариф за худшее качество. Это первое, что стоит проверить в работающем проекте.

Теперь арифметика. Допустим, у вас бот поддержки: системный промпт с правилами компании на 900 токенов, вопрос пользователя в среднем 60 токенов, ответ 200 токенов. Итого 1160 токенов на диалог, из них 77% занимает ваш собственный системный промпт, который отправляется заново при каждом вопросе.

Цифры считаем до запуска, а не после первого счёта. Формула простая: (токены промпта + токены вопроса + токены ответа) × число вызовов ÷ 1000 × цена модели. Точное число токенов в вашем промпте не надо угадывать: на том же API есть ручка /foundationModels/v1/tokenize, которая возвращает разбивку текста на токены.

Цены проверяйте перед запуском. Тарифы Яндекса менялись уже не раз, и менялись в обе стороны. Актуальный прайс всегда лежит в разделе цен документации Yandex AI Studio, это новый адрес, старые ссылки на yandex.cloud/docs/foundation-models теперь редиректят туда же.

Как не спалить бюджет на токенахСкопировано

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

1. Урежьте системный промпт. Он умножается на каждый запрос, поэтому лишний абзац вежливости стоит вам денег ежедневно. Уберите примеры, которые дублируют друг друга, замените развёрнутые объяснения короткими правилами. Промпт на 900 токенов почти всегда сжимается до 300 без потери качества, а это минус две трети расхода на входе.
2. Не отправляйте всю историю диалога. Наивная реализация чата шлёт в модель все предыдущие реплики, и стоимость десятого сообщения выходит в разы выше стоимости первого. Держите последние 3–5 реплик, а старое сжимайте в короткое резюме.
3. Кешируйте типовые ответы. В поддержке 60–80% вопросов повторяются формулировками. Нормализуйте вопрос, считайте от него хеш и складывайте ответ в Redis на сутки. Повторный вопрос не доходит до модели вообще и стоит ноль.
4. Всегда ставьте maxTokens. Без потолка модель на неудачном промпте может написать простыню на две тысячи токенов там, где нужен был один абзац. Потолок работает как стоп-кран и качества не режет.
5. Разведите задачи по моделям. Классификацию обращений, простановку тегов, извлечение полей из текста Lite делает не хуже флагмана и вдвое дешевле. Флагман оставьте там, где ответ читает живой клиент.

Экономит и сам промпт. Хорошо сформулированная инструкция даёт нужный ответ с первого раза, плохая заставляет гонять запрос по три круга и платить трижды. Если проект живёт на API, навык проектирования промптов окупается быстрее любой оптимизации кода: с чего начать, разбираем на странице курсов промпт-инженера.

Поиск по своим документам через эмбеддингиСкопировано

Самый частый запрос к модели в компании звучит так: «отвечай по нашим регламентам, а не по интернету». Загружать регламенты в промпт целиком нельзя: контекст не резиновый, да и платить за 50 страниц при каждом вопросе никто не будет. Задачу решают эмбеддинги.

Эмбеддинг — это перевод текста в вектор чисел, по которому можно измерять смысловую близость. У Яндекса под это две модели: text-search-doc для документов и text-search-query для пользовательских запросов, обе по 0,01 ₽ за 1000 токенов и обе выдают вектор на 256 измерений. Использовать их надо парой: документы векторизуются одной моделью, вопросы другой, они обучены друг под друга.

Схема сборки базы знаний:

1. Режете документы на фрагменты по 300–800 токенов, по смысловым блокам, а не по строкам.
2. Каждый фрагмент прогоняете через text-search-doc и складываете вектор рядом с текстом. Это разовая операция, повторяется только при обновлении документа.
3. Вопрос пользователя прогоняете через text-search-query.
4. Считаете косинусную близость и берёте 3–5 самых близких фрагментов.
5. Только их подставляете в промпт к YandexGPT вместе с вопросом.

Экономика тут приятная: индексация 200 страниц регламентов это около 120 тысяч токенов, то есть примерно 1,2 ₽ разово. Дальше в каждый запрос уходит не вся база, а пара тысяч токенов найденных фрагментов.

import numpy as np


def cosine(a, b):
    a, b = np.array(a), np.array(b)
    return float(a @ b / (np.linalg.norm(a) * np.linalg.norm(b)))


def top_chunks(query_vector, index, k=3):
    scored = [(cosine(query_vector, item["vector"]), item["text"]) for item in index]
    scored.sort(reverse=True, key=lambda pair: pair[0])
    return [text for _, text in scored[:k]]

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

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

Какую модель брать под задачуСкопировано

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

Рабочая тактика: каскад, сначала Lite, флагман только на сложных случаях. Модель попроще обрабатывает поток, а на флагман уходит то, где Lite сам сообщил о неуверенности или где ответ не прошёл валидацию по формату. На реальных объёмах такая схема срезает счёт примерно вдвое при почти том же качестве.

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

Канал основателя Checkroi Вани БуявцаЗабирайте промпты и обучение по нейросетям в моём Телеграм-каналеБольше 3 700 человек уже применяют Claude Code, ChatGPT и другие нейросети в работе, учёбе, бизнесе и жизниПерейти в канал→

Что чаще всего ломается при подключенииСкопировано

• 401 Unauthorized. Чаще всего забыли префикс: в заголовке должно быть Authorization: Api-Key <секрет>, а не просто ключ и не Bearer. Bearer нужен для IAM-токена, у него другой формат.
• 403 Forbidden. Ключ валидный, но у сервисного аккаунта нет роли ai.languageModels.user в этом каталоге. Проверьте, что роль выдана именно тому каталогу, чей folder_id вы шлёте.
• 404 или ошибка про modelUri. Опечатка в адресе модели или чужой folder_id. Формат строгий: gpt://, идентификатор каталога, имя модели, версия.
• 429 Too Many Requests. Упёрлись в квоту на параллельные запросы. Лечится не ретраями в цикле, а очередью с экспоненциальной паузой; квоту при необходимости поднимают через поддержку.
• Ответ обрывается на полуслове. Смотрите статус альтернативы: если пришёл TRUNCATED_FINAL, значит сработал ваш maxTokens, а не сбой модели.
• Счёт больше расчётного. Почти всегда история диалога, которая копится в messages. Сверьте inputTextTokens из логов с длиной промпта, который вы задумывали.

Где освоить YandexGPT и работу с API системноСкопировано

Первый запрос вы отправите по этой инструкции за вечер. Дальше начинается инженерия: очереди, ретраи, кеш, оценка качества ответов, дообучение под свои данные. Это уже не про одну статью, а про профессию. Если хотите разобраться в теме целиком, посмотрите как стать AI-разработчиком, а ниже собраны программы, где облачные модели и API разбирают на практике.

Курс	Школа	Стоимость со скидкой	В рассрочку	Длитель­ность	Обзор курса от Checkroi
Нейросети для изображений и видео Перейти на сайт курса	Эдюсон	47 504 ₽	3958 ₽/мес.	2 месяца	Обзор курса
Нейросети для рабочих задач Перейти на сайт курса	Skillbox	31 290 ₽	2608 ₽/мес.	1 месяц	Обзор курса
Нейросети. Практический курс Перейти на сайт курса	Skillbox	74 900 ₽	6242 ₽/мес.	3 месяца	Обзор курса
Нейросети для каждого: как решать рабочие задачи быстрее Перейти на сайт курса	Нетология	57 000 ₽	2763 ₽/мес.	6 недель	Обзор курса
Продуктовый маркетолог + Нейросети для маркетинга Перейти на сайт курса	Нетология	110 200 ₽	3875 ₽/мес.	5 месяцев	Обзор курса

• 

  Нейросети для изображений и видео

  Эдюсон47 504 ₽3958 ₽/мес2 месяца
  Перейти на сайт курсаОбзор
• 

  Нейросети для рабочих задач

  Skillbox31 290 ₽2608 ₽/мес1 месяц
  Перейти на сайт курсаОбзор
• 

  Нейросети. Практический курс

  Skillbox74 900 ₽6242 ₽/мес3 месяца
  Перейти на сайт курсаОбзор
• 

  Нейросети для каждого: как решать рабочие задачи быстрее

  Нетология57 000 ₽2763 ₽/мес6 недель
  Перейти на сайт курсаОбзор
• 

  Продуктовый маркетолог + Нейросети для маркетинга

  Нетология110 200 ₽3875 ₽/мес5 месяцев
  Перейти на сайт курсаОбзор

Больше программ — в полном каталоге курсов по нейросетям и искусственному интеллекту