An API-compatible model service has an unglamorous but critical job: turn several public request formats into the exact prompt expected by a model, then turn generated tokens back into the response shape expected by the client. deepseek-recipe packages that translation layer for DeepSeek V4 and V4.1.

It does not run the model. It does not open an HTTP port, execute tools, search the web, or store conversations. Keeping that boundary visible will save time in this tutorial: the output is a rendered prompt that an inference backend could consume, not a model answer.

Install the Python binding

The official package requires Python 3.10 or newer:

python3 -m pip install deepseek-recipe

For a reproducible project, install it inside a virtual environment and pin the version after the first verified run. The repository was newly published in September 2026 and its API may still evolve. Record both the Python package version and the V4/V4.1 encoding selected by your application.

The package is backed by a family of Rust crates. Python users do not need to rewrite their service in Rust; the binding exposes the conversion and encoding types required for a normal integration.

Render a minimal V4.1 conversation

Create a small script based on the official example:

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

There are two deliberate stages. request.convert(...) maps the Chat Completions payload into the library’s shared Conversation representation. render_conversation(...) applies the V4.1 prompt encoding. Keeping them separate allows an API service to normalize different external protocols before committing to a model-specific token layout.

The model string in the request is part of the client-facing payload; the selected encoding object controls how the normalized conversation is rendered. Do not infer that any arbitrary model name automatically downloads or selects weights. Your surrounding service must validate the requested model and route the prompt to an appropriate backend.

Try DeepSeek on MidassAI

Inspect before connecting inference

Print the prompt only in a local development fixture, never in production logs containing user data. Confirm that system and user messages are represented in the intended order. Add Unicode, empty content, and multiline examples. If your service supports images or tools, create separate fixtures for each instead of assuming the text-only case proves compatibility.

This is also the right point for golden tests. Store a small set of non-sensitive input payloads and approved structural expectations. Exact encoded output may legitimately change across package versions, so decide whether a version upgrade should update snapshots or fail until reviewed.

At minimum, test:

one system and one user message;
a multi-turn conversation with an assistant response;
thinking mode and each supported reasoning-effort value you expose;
temperature, top_p, and output-token limits at their allowed edges;
a client function tool with arguments;
malformed roles, content types, and unsupported options.

The last group matters because protocol compatibility is also rejection compatibility. A service that silently drops an unsupported field is harder to debug than one that returns a precise error.

Know what the library can translate

The current scope covers Messages, Chat Completions, and Responses-style requests, including streaming and complete responses. The shared representation supports text, images, thinking, and client tool calls. Output parsing covers thinking content, tool calls, JSON objects, and stop sequences.

For Responses requests, tool namespaces and the apply_patch custom tool are supported. That does not mean the library applies patches. It represents and parses the tool call; a host application still decides whether the tool exists, asks for permission, runs it, and returns its result to the model.

V4.1 image preprocessing is available through the image component and OpenCV. Images can arrive as base64 data or external URLs. A production service should set size limits, media-type checks, download timeouts, and network restrictions before handing remote content to preprocessing code.

Handle unsupported fields explicitly

As of the checked release, logprobs and top_logprobs are not supported. Neither are document content, audio or video, file retrieval by file_id, multiple completions through n > 1, or encrypted thinking content.

Structured-output expectations need care. The library can parse JSON object output, but it does not enforce JSON Schema, regular expressions, or strict tool definitions. If your API advertises those guarantees, validation must happen elsewhere. A parsed JSON object can still violate the caller’s schema.

Conversation storage is also outside the package. previous_response_id does not retrieve earlier context. Your HTTP service must resolve stored conversation state and pass the resulting messages into conversion, or reject the field clearly.

Server tools such as web_search are unsupported because the recipe layer does not execute tools. If a client sends such a request, do not turn it into a client function call without documenting the semantic difference.

Add it to an API service without blurring responsibilities

A clean service pipeline has four boundaries:

Authentication, rate limits, body-size limits, and public API validation.
deepseek-recipe normalization and V4/V4.1 encoding.
An inference backend that consumes tokens and produces generated tokens.
Recipe parsing, application-owned tool orchestration, and HTTP streaming.

Keep metrics around each boundary. Request conversion time, time to first generated token, tool wait time, and response serialization time answer different operational questions. Combining them into one latency number makes regressions difficult to locate.

Do not pass rendered prompts through logs or tracing systems by default. Record safe metadata such as message count, content types, encoding version, token count, and conversion errors. If sampled payload logging is unavoidable, make it opt-in, redacted, access-controlled, and short-lived.

When this tutorial is the wrong path

Use deepseek-recipe when you are building or adapting an inference service and need DeepSeek-specific protocol conversion. If you only want to call an existing DeepSeek-compatible endpoint, use that service’s client SDK or HTTP API. Adding a prompt encoder to an application client duplicates server behavior and can make upgrades harder.

The package is most valuable precisely because it is not an all-in-one server. It gives infrastructure teams a shared, testable conversion layer while leaving deployment, scheduling, security, and tools under their control. A successful first integration ends with a verified prompt and a list of unsupported fields—not with a claim that the whole serving stack is complete.

Source checked: deepseek-recipe official repository, accessed 14 September 2026.

Convert API Requests for DeepSeek V4.1 with Python