p2d-duck

Unofficial Python client for duck.ai — DuckDuckGo's free, no-account AI chat interface. Supports every active model, streaming, web search, image generation, retry logic, and multi-turn conversation.

pip install p2d-duck

Models

Installation

Python 3.10 or later is required.

pip install p2d-duck

Dependencies installed automatically: httpx, py-mini-racer, cryptography, html5lib.

Quick start

from duck_ai import DuckChat, gpt5_mini

with DuckChat(model=gpt5_mini) as chat:
    response = chat.ask("What is the speed of light?")
    print(response)

Usage

Single question

from duck_ai import DuckChat, claude

with DuckChat(model=claude) as chat:
    print(chat.ask("Explain quantum entanglement in one paragraph."))

Multi-turn conversation

from duck_ai import DuckChat, gpt5_mini

with DuckChat(model=gpt5_mini) as chat:
    chat.ask("My name is Ada.")
    print(chat.ask("What is my name?"))

Streaming

from duck_ai import DuckChat, gpt5_mini

with DuckChat(model=gpt5_mini) as chat:
    for token in chat.stream("Write a haiku about rain."):
        print(token, end="", flush=True)
    print()

Reasoning mode

Activates extended chain-of-thought on supported models (gpt5_mini, claude, gpt_oss):

from duck_ai import DuckChat, gpt5_mini

with DuckChat(model=gpt5_mini, effort="reasoning") as chat:
    print(chat.ask("Prove that the square root of 2 is irrational."))

Fast mode

Lower-latency responses with reduced reasoning, available on all models:

from duck_ai import DuckChat, gpt5_nano

with DuckChat(model=gpt5_nano, effort="fast") as chat:
    print(chat.ask("Capital of France?"))

Web search

Injects live DuckDuckGo search results into the context before responding:

from duck_ai import DuckChat, gpt5_mini

with DuckChat(model=gpt5_mini) as chat:
    print(chat.ask("What happened in the news today?", web_search=True))

Image generation

Returns raw image bytes (PNG/JPEG depending on the service response):

from duck_ai import DuckChat, image_generation

with DuckChat(model=image_generation) as chat:
    data = chat.generate_image("a red fox in autumn leaves, oil painting style")
    with open("fox.png", "wb") as f:
        f.write(data)

API reference

DuckChat

DuckChat(
    model: str | Model = gpt5_mini,
    effort: str | None = None,       # None | "fast" | "reasoning"
    max_retries: int = 3,
    timeout: float = 60.0,
)

Use as a context manager (with DuckChat(...) as chat:) or call .close() when done.

Model constants

from duck_ai import (
    gpt5_mini,         # gpt-5.4-mini        (default)
    gpt5_nano,         # gpt-5.4-nano
    claude,            # claude-haiku-4-5
    mistral,           # mistral-small-2603
    gpt_oss,           # tinfoil/gpt-oss-120b
    image_generation,  # image-generation
)

You can also pass the raw model ID string directly:

DuckChat(model="claude-haiku-4-5")

List all known model IDs at runtime:

from duck_ai.models import list_models
print(list_models())

Retry behaviour

The client automatically retries on transient failures (challenge errors, 5xx server errors). RateLimitError and ConversationLimitError are terminal — they are not retried.

attempt 1 --[ChallengeError]--> re-solve challenge --> attempt 2 --> ...
                                                          max_retries

Disable retries by setting max_retries=1.

Error reference

from duck_ai.exceptions import RateLimitError, ChallengeError

try:
    response = chat.ask("Hello")
except RateLimitError:
    print("Rate limited — wait before retrying or use a different IP.")
except ChallengeError:
    print("Challenge failed — update py-mini-racer or open an issue.")

Command-line interface

python -m duck_ai [--model MODEL] [--effort EFFORT] [--no-stream] [--web]

# Interactive reasoning session with Claude
python -m duck_ai --model claude-haiku-4-5 --effort reasoning

# Web-aware session with the default model
python -m duck_ai --web

Architecture

duck.ai requires solving a JavaScript proof-of-work challenge before each session. p2d-duck handles this automatically using py-mini-racer, a V8-based JS runtime, together with a DOM stub layer (stubs.js) that emulates the browser APIs the challenge script depends on.

ask("...")
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  DuckChat                                               │
│                                                         │
│  1.  GET /duckchat/v1/status                            │──► duck.ai
│      ◄── x-vqd-hash-1  (base64 JS challenge)           │
│                                                         │
│  2.  challenge.solve_challenge(js, user_agent)          │
│       ├─ decode base64 payload                          │
│       ├─ inject DOM stubs  (stubs.js)                   │
│       ├─ evaluate in V8  (py-mini-racer)                │
│       └─ SHA-256 hash result → token                    │
│                                                         │
│  3.  POST /duckchat/v1/chat                             │──► duck.ai
│      x-vqd-hash-1: <solved token>                      │
│      ◄── SSE stream of tokens                           │
│                                                         │
│  4.  assemble and return                                │
└─────────────────────────────────────────────────────────┘
    │
    ▼
response string

The challenge payload is a self-contained obfuscated JS function that fingerprints DOM geometry (getBoundingClientRect, offsetWidth, offsetHeight, getComputedStyle) and navigator properties (webdriver, userAgent). stubs.js supplies realistic values for each property so the challenge computes the same hash a real browser would.

Rate limits

duck.ai enforces per-IP rate limits. If you receive a RateLimitError, wait a few minutes before retrying. Datacenter and cloud IPs are throttled more aggressively than residential IPs.

Requirements

License

MIT — see LICENSE.

Disclaimer

This project is not affiliated with, endorsed by, or supported by DuckDuckGo. It interfaces with duck.ai's public web UI. DuckDuckGo's terms of service apply. The upstream API may change without notice; open an issue if something breaks.