DeepSeek API на Python: запросы, стриминг, JSON и обработка ошибок

Если вам нужен DeepSeek API на Python, отдельная библиотека не требуется: модели DeepSeek отвечают в OpenAI-совместимом формате, а значит, подходит обычный пакет openai. Ниже рабочий код для deepseek-v4.1-flash и deepseek-v4-pro: обычный запрос, стриминг, ответ в JSON и обработка ошибок с повторами. Доступ из России — через шлюз, оплата СБП, картой MasterCard или криптой.

Подготовка

pip install openai
export ZUKKO_API_KEY="fetch_ваш_ключ"

Ключ создаётся в кабинете Zukko. Храните его в переменной окружения, а не в коде. Общая схема работы с SDK описана в разделе Python↗ документации.

Первый запрос

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["ZUKKO_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {"role": "system", "content": "Отвечай кратко, по-русски."},
        {"role": "user", "content": "Чем список отличается от кортежа в Python?"},
    ],
    max_tokens=400,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Адрес с /v1 на конце обязателен: OpenAI SDK сам добавляет только chat/completions. Поле usage показывает, сколько токенов потрачено, и по нему удобно считать стоимость.

Какую модель DeepSeek выбрать

Цены на 18 октября 2026, $ за 1M токенов:

Пример расчёта для запроса в 2000 входных и 500 выходных токенов:

• V4.1 Flash: 2000 × 0.013 / 1M + 500 × 0.038 / 1M = 0.000026 + 0.000019 = $0.000045.
• V4 Pro: 2000 × 0.075 / 1M + 500 × 0.225 / 1M = 0.00015 + 0.0001125 = около $0.00026.

Если в запросе нужны картинки, из пары подходит только V4 Pro. Для текстовых задач начинайте с Flash и проверьте результат на своих данных; по индексу силы в таблице модели расположены близко, но решает ваш материал, а не индекс. Актуальный список цен: GET https://api.zukko.pro/v1/models.

Стриминг

Стриминг нужен, когда ответ показывают пользователю по мере генерации. Важная деталь: в конце потока сервер присылает чанк со статистикой использования и пустым списком choices, поэтому обращение к choices[0] без проверки упадёт.

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Напиши план статьи про кэширование"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)

Если поток обрывается на полуслове, проверьте max_tokens и finish_reason в последнем чанке с содержимым: значение length означает, что ответ упёрся в лимит.

Ответ в формате JSON

Самый переносимый способ: попросить JSON в промпте, разобрать ответ и при ошибке повторить запрос. Он не зависит от того, поддерживает ли конкретная модель специальный режим JSON.

import json

SYSTEM = (
    "Верни только JSON без пояснений и без markdown. "
    'Схема: {"sentiment": "positive|neutral|negative", "topics": [string]}'
)

def classify(text: str, attempts: int = 3) -> dict:
    for _ in range(attempts):
        r = client.chat.completions.create(
            model="deepseek-v4.1-flash",
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": text},

Параметр response_format={"type": "json_object"} можно добавить в вызов, но поддержка зависит от модели, поэтому проверьте его на своей и всё равно оставляйте проверку через json.loads. Другие приёмы собраны в статье про структурированный ответ→.

Ошибки и ретраи

Клиент OpenAI сам повторяет запрос при сетевых сбоях и части ошибок сервера (по умолчанию дважды), число повторов задаётся параметром max_retries. Остальные ошибки нужно разбирать по смыслу:

import os
import time
import openai

client = openai.OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["ZUKKO_API_KEY"],
    max_retries=2,
    timeout=60,
)

def ask(prompt: str, model: str = "deepseek-v4.1-flash") -> str:
    for attempt in range(4):
        try:

Что означают коды: 401 — неверный ключ, 402 — не хватает баланса, 403 model_not_allowed_for_key — модель не разрешена для этого ключа, 404 model_not_found — неверное имя модели, 413 — слишком большой запрос, 429 — исчерпан лимит ключа или ограничение у провайдера модели, 503 — провайдер недоступен или модель выключена. На 401, 402, 403 и 404 повторять бессмысленно: исправьте причину. Подробнее о стратегии повторов и запасной модели — в статье про fallback и retry→.

Что учесть в продакшене

• Задавайте max_tokens, чтобы одна ошибка в промпте не породила длинный дорогой ответ.
• Заведите отдельный ключ под проект с дневным лимитом в долларах и списком разрешённых моделей.
• Для DeepSeek цена чтения кэша в таблице совпадает с ценой входа, поэтому отдельной скидки за кэш расчёт не даёт.
• Не зашивайте модель в код: вынесите её имя в настройки, чтобы заменить при смене каталога.

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

Нужен ли отдельный ключ DeepSeek?

Нет. Достаточно ключа fetch_... от шлюза: он работает со всеми моделями каталога, в том числе с Claude, GPT и Qwen, поэтому код легко переключить сменой строки model.

Как включить рассуждения?

Названия параметров для режимов рассуждения у разных моделей отличаются, и здесь мы их не приводим. Проверьте в справочнике по chat completions и на практике через usage, как меняется число выходных токенов.

Можно ли отправлять картинки?

Из двух моделей в этой статье картинки на вход принимает deepseek-v4-pro. У deepseek-v4.1-flash в таблице значится «нет».

Что делать, если получил 404?

Скорее всего, опечатка в id модели. Сверьте имя со списком из GET /v1/models: например, deepseek-v4.1-flash, а не deepseek-v4-1-flash.

Чтобы запустить код, создайте ключ в кабинете↗, пополните баланс от $1 и подставьте ключ в переменную окружения.