apideepseek 0.1.1

High-performance async Python client for the private DeepSeek API

apideepseek

apideepseek is an async Python client for the private DeepSeek API. It supports token or email/password authentication, streaming responses, multi-turn conversations, image uploads, model modes, and account registration.

Russian documentation: docs/ru/README.md

Installation

pip install apideepseek

Building from source requires a C++17 compiler with AVX2 support and pybind11 for the PoW extension. See docs/en/pow.md.

Quick Start

Ask One Question

import asyncio
from apideepseek import DeepSeekClient

async def main():
    async with DeepSeekClient(token="YOUR_TOKEN") as client:
        result = await client.ask("Hello!")
        print(result.text)

asyncio.run(main())

You can also log in with email and password:

async with DeepSeekClient(email="[e-mail]", password="password123") as client:
    result = await client.ask("Hello!")
    print(result.text)

Model Modes

Use ModelType when creating the client or for a single request.

Mode	Use When	Code
Fast/default	Normal text chat, fastest general mode	ModelType.DEFAULT
Expert	Harder reasoning or expert answers	ModelType.EXPERT
Vision/recognition	Questions about an image	ModelType.VISION

import asyncio
from apideepseek import DeepSeekClient, ModelType

async def main():
    async with DeepSeekClient(token="YOUR_TOKEN", model=ModelType.DEFAULT) as client:
        fast = await client.ask("Short answer: what is asyncio?")
        expert = await client.ask(
            "Analyze the tradeoffs in detail",
            model=ModelType.EXPERT,
        )
        print(fast.text)
        print(expert.text)

asyncio.run(main())

Attach an Image to a Prompt

The current upload helper supports PNG and JPEG images. It does not upload arbitrary PDF, DOCX, TXT, or ZIP files.

The simplest form is passing Path directly to ask; the client uploads the image and attaches it to the prompt:

import asyncio
from pathlib import Path
from apideepseek import DeepSeekClient, ModelType

async def main():
    async with DeepSeekClient(token="YOUR_TOKEN") as client:
        result = await client.ask(
            "What is shown in this image?",
            image=Path("photo.jpg"),
            model=ModelType.VISION,
        )
        print(result.text)

asyncio.run(main())

If you want to reuse the same image in several requests, upload it once:

img = await client.upload_image(Path("photo.jpg"))
result = await client.ask("Describe the image", image=img, model=ModelType.VISION)

Raw bytes also work:

data = Path("photo.png").read_bytes()
result = await client.ask("Read the text in this image", image=data, model=ModelType.VISION)

Create a New Conversation

Use client.new_conversation() for a multi-turn chat. The Conversation object remembers the last message_id and sends it as parent_message_id on the next turn.

import asyncio
from apideepseek import DeepSeekClient

async def main():
    async with DeepSeekClient(token="YOUR_TOKEN") as client:
        chat = client.new_conversation()
        first = await chat.ask("My name is Alex. Remember it.")
        second = await chat.ask("What is my name?")
        print(first.text)
        print(second.text)

asyncio.run(main())

Create another independent thread by creating another Conversation:

chat_a = client.new_conversation()
chat_b = client.new_conversation()

Streaming

By default ask_stream() yields only new text fragments. Use cumulative=True if you need the full text so far on every iteration.

async for chunk in client.ask_stream("Tell me about Python"):
    print(chunk, end="", flush=True)

Streaming also works inside a conversation:

chat = client.new_conversation()
async for chunk in chat.ask_stream("Explain async/await"):
    print(chunk, end="", flush=True)

Register a New Account

import asyncio
from apideepseek import DeepSeekClient

async def main():
    await DeepSeekClient.send_reg_code("[e-mail]")
    code = input("Code from email: ")
    token = await DeepSeekClient.confirm_reg_code(
        "[e-mail]",
        "password123",
        code,
    )
    print("Token:", token)

asyncio.run(main())

Result Object

ask() and Conversation.ask() return DeepSeekTurnResult:

result = await client.ask("Hello")
print(result.text)        # full assistant response
print(result.session_id)  # DeepSeek chat session id
print(result.message_id)  # assistant message id for threading

Error Handling

from apideepseek import DeepSeekClient, AuthorizationError, DeepSeekError

try:
    async with DeepSeekClient(token="invalid") as client:
        await client.ask("Hello")
except AuthorizationError:
    print("Token is invalid")
except DeepSeekError as e:
    print(f"API error: {e}")

Documentation

• DeepSeekClient methods
• Conversation
• Data types
• Exceptions
• Proof-of-Work

Requirements

• Python 3.9+
• aiohttp >= 3.9
• C++17 compiler with AVX2 to build the PoW extension from source, or a prebuilt wheel