DeepSeek API: полное руководство для AI-инженеров (2026)

DeepSeek API — это OpenAI-совместимый endpoint, который даёт доступ к семейству моделей V4 от DeepSeek — включая V4-Pro (сильнейшая модель для reasoning) и V4-Flash (быстрая и крайне доступная рабочая лошадка). Обе модели поддерживают контекст в 1 млн токенов, опциональный thinking mode, tool calls и JSON output. Для начала: зарегистрируйтесь на platform.deepseek.com, получите API key, укажите https://api.deepseek.com в качестве base_url для вашего OpenAI SDK — и код заработает.

Мы написали это руководство, потому что цены DeepSeek одни из самых низких в индустрии, но линейка V4 внесла новые имена моделей, thinking mode по умолчанию и дедлайн отключения legacy-имён, что может создать подводные камни. Это та самая справка, которая нам нужна была при первой интеграции DeepSeek в наш routing layer.

Быстрый старт за 3 минуты

Шаг 1: Регистрация. Перейдите на platform.deepseek.com и создайте аккаунт. DeepSeek поддерживает email и Google OAuth.

Шаг 2: Получите API key. Откройте API Keys, нажмите «Create API Key». Скопируйте его — ключ показывается только один раз; сохраните в надёжном месте.

Шаг 3: Первый вызов. Установите OpenAI Python SDK:

pip install --upgrade openai

Затем выполните:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DEEPSEEK_KEY",
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Что такое DeepSeek V4?"}],
)

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

Готово. Кредитная карта для старта не требуется. DeepSeek периодически начисляет промо-кредиты — проверьте баланс аккаунта, чтобы узнать доступные средства.

Семейство моделей: V4-Flash и V4-Pro

DeepSeek предлагает две модели через API, обе выпущены в preview 24 апреля 2026:

Обе модели поддерживают thinking и non-thinking режимы. Thinking mode включён по умолчанию — модель генерирует цепочку рассуждений перед финальным ответом.

Legacy имена моделей (deprecated)

DeepSeek отключит два старых model ID 24 июля 2026 в 15:59 UTC:

Если в коде всё ещё используется deepseek-chat или deepseek-reasoner, переключитесь на deepseek-v4-flash прямо сейчас. Мы рекомендуем явно задавать thinking toggle, а не полагаться на неявный выбор режима.

Что изменилось от V3 к V4

Линейка V4 — архитектура четвёртого поколения от DeepSeek. Ключевые отличия от V3.x:

• Единый thinking mode: V4 заменяет отдельную линейку R1 для reasoning — опциональный thinking mode в V4 покрывает задачи, для которых раньше использовался R1. Если вы маршрутизировали на deepseek-r1 для reasoning, переключитесь на deepseek-v4-pro с включённым thinking.
• 1M контекст: V3.x ограничивался 128K; V4 поддерживает 1M токенов на обеих моделях.
• Anthropic API совместимость: V4 добавил Anthropic-формат endpoint по адресу https://api.deepseek.com/anthropic в дополнение к OpenAI формату.
• FIM completion: Fill-in-the-middle completion поддерживается в non-thinking режиме обеих моделей — полезно для code completion workflow.

Источник: DeepSeek V4 Preview Release, retrieved 2026-06-07.

OpenAI SDK: Python, Node.js и streaming

DeepSeek реализует спецификацию OpenAI ChatCompletions. Специальный SDK не нужен — используйте официальный OpenAI SDK и измените base_url.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DEEPSEEK_KEY",
    base_url="https://api.deepseek.com",
)

# Без streaming
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Объясни теорему CAP."}],
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Объясни теорему CAP."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Node.js

import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [{ role: "user", content: "Объясни теорему CAP." }],
});

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

curl

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Привет!"}],
    "stream": false
  }'

Источник: DeepSeek API Docs — Your First API Call, retrieved 2026-06-07.

Thinking Mode: когда и как использовать

Обе модели V4 поддерживают thinking mode — модель генерирует chain-of-thought reasoning перед финальным ответом. Thinking mode включён по умолчанию.

Переключение thinking mode

# Включить thinking (по умолчанию)
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Докажи, что √2 иррационально."}],
    extra_body={"thinking": {"type": "enabled"}},
    reasoning_effort="high",
)

# Отключить thinking
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Сколько будет 2+2?"}],
    extra_body={"thinking": {"type": "disabled"}},
)

Уровни усилий

• high — по умолчанию для обычных запросов
• max — автоматически используется некоторыми Agent инструментами (Claude Code, OpenCode); даёт более глубокий reasoning при повышенной латентности

Доступ к reasoning content

В thinking mode цепочка рассуждений возвращается в поле reasoning_content рядом с обычным content:

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "9.11 и 9.8 — какое больше?"}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

reasoning = response.choices[0].message.reasoning_content  # chain of thought
answer = response.choices[0].message.content               # финальный ответ

Multi-turn диалоги с thinking

Когда между ходами нет tool calls, reasoning_content из предыдущих ходов не нужно включать в последующие запросы — API DeepSeek игнорирует его автоматически. Однако при наличии tool calls reasoning_content обязательно передаётся во всех последующих ходах — иначе API вернёт ошибку 400.

Когда отключать thinking

• Простые фактические запросы — thinking добавляет латентность без прироста качества
• High-throughput чат — отключите thinking для максимального преимущества по concurrency у V4-Flash
• Cost-sensitive сценарии — thinking-токены тарифицируются по output-ценам

Источник: DeepSeek API Docs — Thinking Mode, retrieved 2026-06-07.

Tool Calls и JSON Output

Обе модели V4 поддерживают function/tool calling и структурированный JSON output, совместимые со спецификацией OpenAI.

Tool Calls

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Получить текущую погоду для города",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Название города"},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Какая погода в Пекине?"}],
    tools=tools,
    tool_choice="auto",
)

if response.choices[0].message.tool_calls:
    call = response.choices[0].message.tool_calls[0]
    print(f"Функция: {call.function.name}")
    print(f"Аргументы: {json.loads(call.function.arguments)}")

JSON Output

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Отвечай в формате JSON."},
        {"role": "user", "content": "Перечисли 3 языка программирования и год их создания."},
    ],
    response_format={"type": "json_object"},
)
print(json.loads(response.choices[0].message.content))

FIM Completion (code completion)

Обе модели поддерживают fill-in-the-middle в non-thinking режиме:

response = client.completions.create(
    model="deepseek-v4-flash",
    prompt="def fibonacci(n):\n    ",
    suffix="    return fib",
)
print(response.choices[0].text)

Источник: DeepSeek API Docs — Tool Calls, retrieved 2026-06-07.

Pricing и Rate Limits

Цены (за 1M токенов)

Источник: DeepSeek API Docs — Models & Pricing, retrieved 2026-06-07. Цены могут измениться.

Цена cache hit примерно в 50 раз дешевле cache miss. Это делает DeepSeek особенно выгодным для рабочих нагрузок, повторяющих один и тот же system prompt или длинный контекст — RAG пайплайны, Agent циклы, инструменты анализа кода с общим префиксом.

Rate Limits (concurrency)

DeepSeek измеряет concurrency на уровне аккаунта — запрос занимает слот с момента отправки до завершения ответа. Превышение лимита возвращает HTTP 429. Отдельных лимитов на токены/минуту или запросы/минуту, помимо concurrency, нет.

Если нужен более высокий concurrency, DeepSeek предоставляет форму заявки на расширение без дополнительной платы.

Источник: DeepSeek API Docs — Rate Limit & Isolation, retrieved 2026-06-07.

Billing

DeepSeek работает по предоплате (пополненный или подаренный баланс). Промо-кредиты расходуются первыми. Цены могут корректироваться — DeepSeek рекомендует пополнять баланс исходя из фактического использования и регулярно проверять pricing страницу.

Частые ошибки и решения

Подводные камни thinking mode

• temperature / top_p игнорируются в thinking mode: Установка этих параметров не вызовет ошибку, но не имеет эффекта при включённом thinking.
• Отсутствие reasoning_content в ходах с tool calls: Если модель выполнила tool call, reasoning_content должен быть передан в последующих запросах. Пропуск ведёт к ошибке 400.
• Совместимость reasoning_effort: low и medium молча маппятся в high; xhigh маппится в max. Не используйте их как отдельные уровни.

Keep-alive механизм

Когда запрос ожидает inference, API DeepSeek отправляет периодические keep-alive сигналы (пустые строки для non-streaming, SSE-комментарии для streaming). При ручном парсинге HTTP-ответов обрабатывайте их корректно. Если inference не начат в течение 10 минут, сервер закрывает соединение.

Источник: DeepSeek API Docs — FAQ, retrieved 2026-06-07.

Маршрутизация DeepSeek с резервными провайдерами

Для production-приложения зависимость от одного провайдера — это риск. Вот как мы рекомендуем маршрутизировать DeepSeek:

С TheRouter

Если вы используете TheRouter, вы можете настроить DeepSeek как одного из провайдеров. TheRouter маршрутизирует OpenAI-совместимые запросы через настроенных провайдеров и поддерживает provider/model fallback, когда live product paths это обеспечивают. Это значит, что вы можете поставить DeepSeek как основной, а другой провайдер как резервный — без изменения кода приложения.

Ручной fallback паттерн

Если вы управляете fallback самостоятельно:

import openai
import time

providers = [
    {"name": "deepseek", "base_url": "https://api.deepseek.com", "model": "deepseek-v4-flash", "key": "DS_KEY"},
    {"name": "siliconflow", "base_url": "https://api.siliconflow.cn/v1", "model": "deepseek-v4-flash", "key": "SF_KEY"},
    {"name": "other", "base_url": "https://api.other-provider.com/v1", "model": "deepseek-v4-flash", "key": "OTHER_KEY"},
]

for provider in providers:
    try:
        client = openai.OpenAI(api_key=provider["key"], base_url=provider["base_url"])
        response = client.chat.completions.create(
            model=provider["model"],
            messages=[{"role": "user", "content": "Привет!"}],
            timeout=30,
        )
        print(f"Успех через {provider['name']}")
        break
    except Exception as e:
        print(f"{provider['name']} не удался: {e}")
        time.sleep(1)

Модели DeepSeek широко доступны через агрегаторы вроде SiliconFlow, что обеспечивает географическую резервность при региональных проблемах с API DeepSeek.

Чеклист перед продакшеном

Перед запуском DeepSeek в production:

• Переключитесь с legacy имён моделей — если используете deepseek-chat или deepseek-reasoner, мигрируйте на deepseek-v4-flash до 24 июля 2026
• Явно задавайте thinking mode — не полагайтесь на дефолты; передавайте {"thinking": {"type": "enabled"}} или {"type": "disabled"} в зависимости от use case
• Обрабатывайте reasoning_content в ходах с tool calls — передавайте обратно в последующих запросах, чтобы избежать ошибки 400
• Мониторьте concurrency — V4-Flash: лимит 2,500; V4-Pro: 500
• Настройте fallback провайдера — не зависьте от одного API эндпоинта для production трафика
• Используйте кэширование контекста — DeepSeek disk-based cache делает повторные system prompts крайне дешёвыми ($0.0028/1M для V4-Flash cache hits)
• Используйте user_id для multi-tenant isolation — передавайте параметр user_id для изоляции контентной безопасности, KVCache и scheduling между вашими пользователями
• Настройте timeouts — установите разумный timeout (например, 60s) во избежание зависания соединений на длительных thinking запросах
• Пополняйте баланс заранее — DeepSeek работает по предоплате; регулярно проверяйте баланс

FAQ

Q: Можно ли использовать DeepSeek с Claude Code или GitHub Copilot? A: Да. DeepSeek поддерживает прямую интеграцию с Agent инструментами: Claude Code, GitHub Copilot, OpenCode. См. Agent Integrations Guide.

Q: В чём разница между V4-Flash и V4-Pro? A: V4-Pro — более сильная модель для reasoning, выше на сложных бенчмарках, лучше справляется с многошаговым анализом. V4-Flash быстрее, дешевле и имеет в 5 раз выше concurrency (2,500 vs 500). Используйте V4-Flash для большинства production рабочих нагрузок; V4-Pro — когда нужен глубокий reasoning или сложные tool-call цепочки.

Q: Thinking-токены оплачиваются отдельно? A: Да. Thinking-токены (output reasoning_content) тарифицируются по output-ценам. Если глубокий reasoning не нужен, отключите thinking mode для экономии.

Q: DeepSeek API действительно совместим с OpenAI? A: Да — endpoint реализует спецификацию OpenAI ChatCompletions. Любой инструмент, SDK или код, работающий с OpenAI форматом, работает с DeepSeek после изменения base_url и API key. DeepSeek также поддерживает Anthropic-формат endpoint по адресу https://api.deepseek.com/anthropic.

Q: Как работает context caching? A: DeepSeek использует disk-based context caching. Когда несколько запросов разделяют один и тот же префикс (system prompt, общий контекст), только первый запрос платит полную input-цену. Последующие запросы с тем же префиксом оплачиваются по цене cache hit — $0.0028/1M для V4-Flash вместо $0.14/1M без кэша. Происходит автоматически, конфигурация не требуется.

Q: Можно ли запустить модели DeepSeek локально? A: Да. Веса V4-Flash и V4-Pro доступны на HuggingFace под MIT лицензией. Однако для локального развёртывания нужны значительные GPU ресурсы. Для production использования API проще и экономичнее.

Q: Что случилось с DeepSeek-R1? A: Thinking mode в V4 фактически заменяет линейку R1 для reasoning. Если вы использовали deepseek-r1 для сложного reasoning, переключитесь на deepseek-v4-pro с включённым thinking. R1 всё ещё доступен через сторонние провайдеры вроде SiliconFlow, но собственный API DeepSeek фокусируется на линейке V4.

---

Последнее обновление: 7 июня 2026. Цены и доступность моделей из DeepSeek API Docs. Все цены могут измениться — проверяйте актуальные тарифы на platform.deepseek.com перед бюджетированием.