Запрос к endpoint https://api.deepseek.com возвращает ошибку 401 Unauthorized в подавляющем большинстве случаев по одной причине — в заголовке нет действительного API-ключа, а сам ключ создаётся не на странице чата, а в отдельном разделе платформы разработчика. Прежде чем искать сбой в коде, проверьте, что ключ сгенерирован именно в кабинете DeepSeek Platform и передаётся в заголовке Authorization: Bearer.
Эта статья разбирает работу с API DeepSeek от регистрации до обработки типовых ошибок: как получить ключ, какие модели доступны, как сформировать первый запрос и почему баланс может уходить в минус. Материал ориентирован на разработчиков и продвинутых пользователей, которые хотят встроить модели DeepSeek в свои приложения, скрипты или сервисы.
Что такое API DeepSeek и чем он отличается от чата
DeepSeek известен большинству пользователей как веб-чат, однако для интеграции в программы существует отдельный программный интерфейс — DeepSeek API. Базовый адрес для всех запросов — https://api.deepseek.com, а структура эндпоинтов совместима с форматом OpenAI API, что заметно упрощает миграцию существующих проектов.
Ключевое отличие от веб-версии — модель оплаты. Чат может быть доступен бесплатно, тогда как вызовы API тарифицируются по количеству обработанных токенов: отдельно учитываются входные данные (ваш промпт) и выходные (ответ модели). Точные цены периодически меняются, поэтому актуальный прайс всегда стоит смотреть в официальной документации платформы, а не полагаться на цифры из сторонних обзоров.
Важно понимать и различие учётных записей: аккаунт для чата и аккаунт платформы разработчика исторически разделены. Баланс и ключи API управляются именно в кабинете платформы, и пополнение там происходит отдельно.
Регистрация и получение API-ключа
Чтобы начать работу, необходимо зарегистрироваться на платформе разработчика DeepSeek. Процедура стандартная: указывается email или используется вход через сторонний аккаунт, после чего открывается доступ к панели управления. Точный набор способов входа может меняться, поэтому ориентируйтесь на текущую форму регистрации на сайте.
Ключ создаётся в разделе управления API-ключами (обычно он называется API Keys). При создании ключу можно дать произвольное имя — это удобно, когда ключей несколько: для тестов, для продакшена, для разных проектов.
⚠️ Внимание: полное значение API-ключа показывается только один раз — в момент создания. Сразу скопируйте его в надёжное хранилище (менеджер паролей или переменные окружения). Если ключ утерян, восстановить его нельзя — придётся создавать новый и отзывать старый.
☑️ Подготовка к первому запросу
Структура запроса и доступные модели
Основная точка входа для диалоговых запросов — POST https://api.deepseek.com/chat/completions. Тело запроса содержит название модели, массив сообщений и опциональные параметры вроде температуры и ограничения длины ответа.
На момент написания материала в API доступны модели семейства deepseek-chat и deepseek-reasoner. Первая ориентирована на универсальные задачи — генерацию текста, перевод, ответы на вопросы. Вторая — модель рассуждающего типа, которая перед ответом строит цепочку рассуждений и лучше справляется с математикой, логикой и сложным кодом. Состав моделей и их идентификаторы могут обновляться, поэтому актуальный список проверяйте в документации.
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ВАШ_КЛЮЧ" \
-d '{
"model": "deepseek-chat",
"messages": [
{"role": "system", "content": "Ты полезный ассистент."},
{"role": "user", "content": "Привет!"}
]
}'
Если вы ранее работали с OpenAI SDK, переход занимает минуты: в клиенте меняется base_url на https://api.deepseek.com и подставляется ключ DeepSeek. Остальная логика — сообщения, стриминг, параметры — работает аналогично.
Тарификация, баланс и контроль расходов
Оплата в API DeepSeek построена на токенах. Токен — это фрагмент текста: для русского языка один токен примерно соответствует части слова, поэтому длинные запросы и развёрнутые ответы расходуют баланс быстрее, чем кажется. Отдельно тарифицируются входные и выходные токены, причём цена за них обычно различается.
У модели deepseek-reasoner есть особенность: в стоимость ответа входят и токены внутренних рассуждений, которые не всегда видны пользователю в финальном тексте. Это нужно учитывать при оценке бюджета на рассуждающие задачи.
- 💰 Установите лимит расходов в кабинете, если такая функция доступна, — это защитит от неожиданного списания при ошибке в цикле скрипта.
- 📊 Логируйте поле
usageиз каждого ответа API — там указано точное число потраченных токенов. - ✂️ Ограничивайте
max_tokensтам, где длинный ответ не нужен. - 🗜️ Сокращайте системные промпты и историю диалога — они оплачиваются при каждом запросе заново.
Типовые ошибки и их диагностика
Большинство проблем при работе с api.deepseek.com сводится к нескольким HTTP-кодам. Ниже — таблица с типичными ситуациями; точные тексты сообщений могут отличаться в зависимости от версии API.
| Код | Вероятная причина | Что проверить |
|---|---|---|
| 401 | Ключ отсутствует, неверен или отозван | Заголовок Authorization, актуальность ключа в кабинете |
| 402 | Недостаточно средств на балансе | Остаток средств и историю списаний |
| 400 | Некорректное тело запроса | Название модели, формат поля messages |
| 429 | Превышен лимит запросов | Частоту запросов, добавьте повторные попытки с паузой |
| 500/503 | Сбой или перегрузка на стороне сервиса | Повторить запрос позже, проверить статус сервиса |
Отдельный частый случай — ошибка 402 при визуально «рабочем» ключе. Ключ может быть полностью валидным, но запросы будут отклоняться, пока на балансе платформы нет средств — это не баг, а штатное поведение биллинга.
⚠️ Внимание: не встраивайте бесконечный цикл повторных запросов без задержки при ошибке 429. Это усугубляет ограничение и может привести к временной блокировке. Используйте экспоненциальную паузу между попытками.
Хранение ключей и безопасность
API-ключ — это фактически пароль к вашему балансу. Любой, кто получит к нему доступ, сможет тратить ваши средства через API. Поэтому правила обращения с ключом строгие, и они не зависят от конкретного языка программирования.
- 🔐 Храните ключ в переменных окружения или секретах CI/CD, а не в исходном коде.
- 🚫 Никогда не публикуйте ключ в репозиториях — даже в приватных, если к ним есть доступ у третьих лиц.
- 🔄 При малейшем подозрении на утечку немедленно отзовите ключ в кабинете и создайте новый.
- 🧩 Для разных проектов и окружений используйте отдельные ключи — так проще отозвать скомпрометированный, не ломая остальные системы.
⚠️ Внимание: если ключ случайно попал в коммит, простого удаления файла из репозитория недостаточно — он остаётся в истории Git. Ключ нужно отозвать на стороне платформы, только это гарантирует его обессмысливание.
Как организовать ключи в командной разработке
Заведите отдельный ключ на каждое окружение: development, staging, production. Доступ к production-ключу ограничьте минимальным кругом разработчиков и храните его в секрет-хранилище (Vault, секреты облачного провайдера). Регулярно проверяйте логи использования в кабинете платформы — всплеск активности с незнакомого окружения — признак утечки.
Стриминг ответов и работа с длинными генерациями
Для чат-интерфейсов и длинных ответов полезен режим стриминга: параметр stream: true заставляет API отдавать ответ частями по мере генерации. Пользователь видит текст сразу, а не ждёт полного завершения запроса, что заметно улучшает воспринимаемую скорость приложения.
Технически стриминг реализован через Server-Sent Events: ответ приходит потоком фрагментов, которые клиент склеивает. Большинство SDK, совместимых с форматом OpenAI, умеют обрабатывать такой поток автоматически — достаточно включить соответствующую опцию.
Для фоновых задач, где скорость отображения не важна (например, пакетная обработка документов), стриминг можно не использовать — обычный запрос проще в обработке и надёжнее при нестабильном соединении.
Ограничения и практические рекомендации
У API есть технические ограничения, которые стоит учитывать на этапе проектирования. Размер контекста модели ограничен: очень длинные документы не поместятся в один запрос, их придётся разбивать на части или использовать методы извлечения релевантных фрагментов. Точные лимиты контекста зависят от модели и указаны в документации.
Скорость ответа и стабильность сервиса могут варьироваться в зависимости от нагрузки. Для критичных систем закладывайте обработку таймаутов и повторные попытки, а также мониторинг доли неудачных запросов.
Что делать, если API отвечает медленно
Проверьте, не используете ли вы рассуждающую модель там, где достаточно обычной — deepseek-reasoner отвечает дольше по своей природе. Сократите входной контекст и max_tokens. Если задержки системные, реализуйте очередь запросов на своей стороне и кэшируйте повторяющиеся результаты.
Часто задаваемые вопросы
Совместим ли API DeepSeek с библиотеками для OpenAI?
Да, API построен в совместимом формате. В большинстве случаев достаточно изменить base_url на https://api.deepseek.com и подставить ключ DeepSeek. Отдельные специфические параметры могут отличаться — их стоит сверить с документацией.
Почему запрос возвращает 401, хотя ключ скопирован правильно?
Проверьте, что ключ создан именно в кабинете платформы разработчика, а не где-либо ещё, что он не был отозван и что в заголовке нет лишних пробелов или переносов строк. Также убедитесь, что используется схема Bearer.
Чем deepseek-chat отличается от deepseek-reasoner?
Первая модель — универсальная, для повседневных задач генерации и диалога. Вторая — рассуждающая: она строит цепочку размышлений перед ответом, лучше решает сложные логические и математические задачи, но отвечает дольше и расходует больше токенов.
Как узнать, сколько токенов потратил запрос?
В каждом ответе API присутствует объект usage с количеством входных и выходных токенов. Сохраняйте эти значения в лог — это основа для контроля расходов.
Можно ли использовать один ключ в нескольких проектах?
Технически можно, но практичнее создать отдельный ключ на каждый проект или окружение. Тогда при утечке или необходимости отзыва вы не остановите работу остальных систем, а статистика расходов будет прозрачнее.