DeepSeek API и SDK

DeepSeek предоставляет OpenAI- и Anthropic-совместимый API для текстовой генерации, рассуждений, вызова функций и обработки изображений экспериментальной моделью. Это руководство поможет подключить API, выбрать модель, управлять режимом рассуждений и проверить результат минимальным запросом.

Содержание

1. Модели и интерфейсы — какие идентификаторы доступны и чем они отличаются.
2. Подключение по OpenAI API — минимальные примеры для Python и TypeScript.
3. Режим рассуждений — параметры thinking, reasoning_effort и reasoning_content.
4. Tool calls и JSON Output — вызов функций и структурированный ответ.
5. Изображения — ограничения экспериментальной vision-модели.
6. Тарифы и кеширование — что учитывать при расчёте стоимости.
7. Полезные сценарии — где использовать Flash, Pro и vision.
8. Проверка результата — наблюдаемые признаки корректного подключения.

Какие модели доступны через API

Основной адрес OpenAI-совместимого API: https://api.deepseek.com. Для Anthropic-совместимого формата используется https://api.deepseek.com/anthropic.

Обе основные модели поддерживают thinking mode: режим рассуждений включается и выключается параметром запроса. DeepSeek также заявляет нативную поддержку формата OpenAI Responses API для Flash и Pro.

Подключение через OpenAI SDK

Получите ключ на DeepSeek Platform и передайте его приложению через переменную окружения. Не храните ключ непосредственно в коде.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ['DEEPSEEK_API_KEY'],
    base_url='https://api.deepseek.com',
)

response = client.chat.completions.create(
    model='deepseek-v4-flash',
    messages=[
        {'role': 'user', 'content': 'Объясни архитектуру Mixture of Experts'}
    ],
    extra_body={'thinking': {'type': 'disabled'}},
)

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

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: 'https://api.deepseek.com',
});

const response = await client.chat.completions.create({
  model: 'deepseek-v4-flash',
  messages: [{ role: 'user', content: 'Hello' }],
  thinking: { type: 'disabled' },
});

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

В OpenAI SDK для Python нестандартное поле thinking передаётся через extra_body. В Node.js оно указывается непосредственно в объекте запроса.

Управление режимом рассуждений

Параметр thinking выбирает режим:

• {'type': 'enabled'} — модель сначала формирует рассуждение, затем итоговый ответ;
• {'type': 'disabled'} — модель возвращает ответ без thinking mode.

Глубина рассуждений задаётся через reasoning_effort. Официально поддерживаются значения low, high и max; значение по умолчанию — high. Для совместимости medium и xhigh преобразуются в high.

response = client.chat.completions.create(
    model='deepseek-v4-pro',
    messages=[{'role': 'user', 'content': 'Реши задачу и объясни ответ'}],
    reasoning_effort='high',
    extra_body={'thinking': {'type': 'enabled'}},
)

message = response.choices[0].message
print(message.reasoning_content)
print(message.content)

В thinking mode рассуждение возвращается в reasoning_content, а итоговый ответ — в content. В статистике использования reasoning-токены доступны отдельно как completion_tokens_details.reasoning_tokens.

Если в последующих запросах не передаётся tools, возвращать в них старое reasoning_content не требуется: API его игнорирует. При наличии tools действуют отдельные правила, описанные ниже.

Параметры temperature, top_p, presence_penalty и frequency_penalty в thinking mode не влияют на результат. API сохраняет совместимость и не обязательно вернёт ошибку, если они указаны.

Tool calls и передача reasoning_content

DeepSeek принимает описания функций в OpenAI-совместимом поле tools. Поддерживается до 128 функций, а аргументы описываются JSON Schema.

tools = [
    {
        'type': 'function',
        'function': {
            'name': 'search_database',
            'description': 'Поиск по базе данных',
            'parameters': {
                'type': 'object',
                'properties': {
                    'query': {'type': 'string'},
                    'limit': {'type': 'integer', 'default': 10},
                },
                'required': ['query'],
            },
        },
    }
]

messages = [
    {'role': 'user', 'content': 'Найди последние заказы'}
]

response = client.chat.completions.create(
    model='deepseek-v4-pro',
    messages=messages,
    tools=tools,
    reasoning_effort='high',
    extra_body={'thinking': {'type': 'enabled'}},
)

messages.append(response.choices[0].message)

Если в запросе передан tools, в каждом последующем запросе передавайте полное сообщение ассистента вместе с reasoning_content, в том числе после шага без нового вызова инструмента. При потере этого поля API вернёт ошибку 400. Проще всего добавлять в историю объект response.choices[0].message целиком.

Аргументы функции приходят строкой в tool_calls[].function.arguments. Проверяйте JSON, типы и допустимые значения до вызова своего кода: документация предупреждает, что модель может сформировать некорректный JSON или добавить отсутствующие в схеме параметры.

JSON Output

Для гарантированно валидного JSON установите response_format:

response = client.chat.completions.create(
    model='deepseek-v4-flash',
    messages=[
        {
            'role': 'system',
            'content': 'Верни JSON с полями title и summary.',
        },
        {'role': 'user', 'content': 'Суммируй описание продукта'},
    ],
    response_format={'type': 'json_object'},
    extra_body={'thinking': {'type': 'disabled'}},
)

Инструкция вернуть JSON должна присутствовать в системном или пользовательском сообщении. Без неё модель может генерировать пробелы до достижения лимита токенов. Режим гарантирует валидный JSON, но при finish_reason со значением length сообщение может быть частично обрезано. Даже при JSON Output проверяйте прикладную схему после получения ответа: этот режим не гарантирует соответствие произвольной бизнес-схеме.

Анализ изображений

Изображения принимает только экспериментальная модель deepseek-v4-flash-vision-exp. Текстовые deepseek-v4-flash и deepseek-v4-pro не следует использовать для мультимодального ввода.

Vision-модель принимает JPEG, PNG, GIF и WebP через URL, Base64 data URL или файл, загруженный через Files API. Поле detail поддерживает значения low, high, original и auto.

response = client.chat.completions.create(
    model='deepseek-v4-flash-vision-exp',
    messages=[
        {
            'role': 'user',
            'content': [
                {'type': 'text', 'text': 'Опиши изображение'},
                {
                    'type': 'image_url',
                    'image_url': {
                        'url': 'https://example.com/image.png',
                        'detail': 'auto',
                    },
                },
            ],
        }
    ],
)

Тарифы и контекстное кеширование

DeepSeek учитывает входные токены отдельно для попаданий и промахов контекстного кеша. Эти значения возвращаются как prompt_cache_hit_tokens и prompt_cache_miss_tokens.

С 16 августа 2026 года действует пиковое и внепиковое ценообразование; согласно журналу изменений, внепиковая цена составляет половину пиковой. Точные ставки зависят от модели и периода, поэтому перед расчётом бюджета сверяйтесь с официальной страницей тарифов.

Для оценки расходов записывайте из ответа:

• prompt_cache_hit_tokens;
• prompt_cache_miss_tokens;
• completion_tokens;
• completion_tokens_details.reasoning_tokens при thinking mode.

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

Полезные сценарии

Массовая обработка текстов

Задача: классифицировать или суммировать большое число однотипных документов.

Используйте deepseek-v4-flash с отключённым thinking mode. Повторяющийся системный промпт может попадать в контекстный кеш. Проверяйте результат по доле корректно разобранных ответов и полям usage. Для строгой структуры добавьте JSON Output и собственную валидацию схемы.

Многошаговая задача с инструментами

Задача: получить данные из нескольких внутренних функций и сформировать итоговый ответ.

Используйте Flash или Pro с tools. Если включены рассуждения, сохраняйте полное сообщение ассистента на каждом шаге. Результат считается корректным, когда цикл завершается без tool_calls, поле content содержит финальный ответ, а все аргументы функций прошли проверку приложения.

Анализ изображения

Задача: описать загруженную схему, фотографию или интерфейс.

Используйте только deepseek-v4-flash-vision-exp. Проверьте поддерживаемый формат и сравните ответ с заранее размеченным набором примеров. Экспериментальный статус делает такой тест обязательным перед производственным использованием.

Как проверить подключение

После выполнения минимального текстового примера проверьте четыре признака:

• HTTP-запрос завершился без ошибки авторизации;
• response.choices[0].message.content содержит непустой ответ;
• поле model указывает на выбранную модель;
• объект usage содержит число входных и выходных токенов.

Для thinking mode дополнительно проверьте reasoning_content и completion_tokens_details.reasoning_tokens. Для tool calls убедитесь, что finish_reason принимает значение tool_calls, аргументы валидируются до исполнения, а после передачи результатов инструментов модель возвращает финальный content.

Если API отклоняет название модели, сначала проверьте, не осталось ли в коде deepseek-chat или deepseek-reasoner.

Чеклист интеграции

Официальные ссылки

• Первый вызов API
• Chat Completions API
• Thinking Mode
• Тарифы
• Журнал изменений

Следующий шаг

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

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

• База знаний: DeepSeek — линейка открытых моделей и API

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov