deepseek-go: a Go client for the DeepSeek V4 API

Two model constants carry the current lineup

The supported-model section is short and deliberate. The current lineup is two entries. deepseek-v4-flash is the flagship, with 1M context and 384K max output, and it supports thinking mode, tool calls, JSON output, FIM, and prefix completion. deepseek-v4-pro is the premium reasoning model, sharing the same 1M context and 384K max output ceiling, and is aimed at complex reasoning and agent tasks. You select either with a constant rather than a string, so a typo becomes a compile error instead of a runtime surprise. Both are referenced as Model fields on a ChatCompletionRequest. Installing the module is a single go get against the module path, and the module targets a specific Go language version:

go get github.com/cohesion-org/deepseek-go

The go.mod pins the language directive, so an older toolchain will refuse the module rather than miscompile it. Beyond chat, the client can check account balance and list the models available to a key, and the project points readers at DeepSeek's own status page for API uptime, which keeps availability questions separate from SDK behaviour.

Deprecated model names still resolve, but warn on stderr

Two older identifiers remain in the SDK for compatibility rather than being removed. deepseek-chat and deepseek-reasoner are both marked deprecated with a sunset date of 2026-07-24. They do not point at separate models. deepseek-chat maps onto the deepseek-v4-flash non-thinking path, and deepseek-reasoner maps onto the deepseek-v4-flash thinking path, so a caller that upgrades without changing its identifier keeps working until the sunset. What changes is feedback: using either deprecated name makes the client emit a deprecation warning to stderr. That is a useful design, because it surfaces the migration during testing rather than failing silently at the deadline. The catch is that the warning is easy to lose in a busy log stream, and the constants themselves keep compiling, so nothing forces a fix until the date actually passes.

Any OpenAI-shaped provider fits through a base URL override

Beyond DeepSeek itself, the client reaches other hosts by overriding the base URL at construction time. Azure DeepSeek R1 and OpenRouter ship as ready constants, and Ollama is supported as well. The Azure endpoint is an inference URL, and the OpenRouter endpoint is its own API path; both are passed into the client constructor alongside a key read from an environment variable. For providers with no dedicated constant, the documented path is to extend the base URL and pass the model name as a plain string in the Model field. The stated limit is explicit: it works as long as the provider follows the same API structure as Azure or OpenRouter. So this is a URL swap for OpenAI-compatible hosts, not a general adapter layer, and a provider that diverges on request or response shape will need the client's internal mappers touched instead. Constructor options get their own example, which suggests the client exposes a variant taking explicit options rather than only positional arguments, and a base_url.go and config.go sit at the top of the tree so the endpoint is a configuration concern rather than something hardcoded into each request path.

Thinking mode and strict tool calling are separate switches

Two of the more advanced behaviours are exposed as distinct, named options rather than being folded into one reasoning flag. Thinking mode delivers chain-of-thought reasoning and is controlled by a reasoning effort setting that accepts high or max. Tool calling has a standard mode and a strict mode, and the strict mode is flagged as beta; it routes automatically to a beta path on the server side. That auto-routing is convenient because callers do not hand-assemble a beta URL, but it also means the effective endpoint differs depending on the flag you set. Separately, an Anthropic-compatible endpoint is available through a dedicated constructor, supporting content blocks, tool use, and streaming, so code written against Anthropic's message shape can be pointed at DeepSeek. The examples directory carries dedicated folders for reasoning effort, strict tools, and the Anthropic client, which makes each switch easy to see in isolation.

Request structs carry tuning parameters directly

Sampling controls live on the request struct rather than behind a builder, which keeps call sites short. The shape below shows a request carrying a model, a system and user message, a temperature, a stop sequence, and a response format all at once:

	request := &deepseek.ChatCompletionRequest{
		Model: deepseek.DeepSeekV4Flash,
		Messages: []deepseek.ChatCompletionMessage{
			{Role: deepseek.ChatMessageRoleUser, Content: "What is the meaning of deepseek"},
			{Role: deepseek.ChatMessageRoleSystem, Content: "Answer every question using slang"},
		},
		Temperature: 1.0,
		Stop:        []string{"yo", "hello"},
		ResponseFormat: &deepseek.ResponseFormat{
			Type: "text",
		},
	}

The response format field is what backs structured JSON output with schema extraction. Beyond chat, the package exposes fill-in-the-middle completion for code generation with streaming, token usage tracking, and client-side token counting that handles both Chinese and English text. Passing an empty key to the constructor is also treated specially: it triggers an environment lookup for the API key rather than sending an empty credential. Token usage is tracked on responses, and a client-side counter estimates token counts for both Chinese and English text before a request goes out. Image handling is present too, exercised by an OpenRouter images example rather than by a first-party DeepSeek model.

The test suite separates unit runs from the live API

The Makefile treats the network as a separate dimension from correctness. A plain test target runs the full suite verbosely, a short variant adds the short flag for fast local iteration, and a race variant adds race detection. Live traffic is isolated behind its own target that sets a live-tests environment variable and an integration build tag together, so the default run never reaches the real API. That split is reinforced in the source tree, where a dedicated integration test file sits alongside the ordinary per-file tests. Linting is pinned as well: the target downloads a specific golangci-lint release into a cache directory and runs it, rather than trusting whatever version happens to be on the machine. The aggregate target runs lint and then tests, giving contributors one command that reproduces what CI does. The example directories, numbered from external providers through multi-turn chat, balance, streaming, FIM, JSON mode, and function calling, double as runnable documentation for each feature area. The numbering makes the reading order explicit: external providers, chat, streaming, FIM, JSON mode, multi-turn chat, balance, constructor options, prefix completion, token usage, list models, function calling, OpenRouter images, reasoning effort, user id, strict tools, and the Anthropic client.

go.mod retracts two releases as premature

The module file does something unusual: it retracts versions. Two releases, v1.1.0 and v1.0.1, are marked as retracted, with a comment explaining they were premature and pointing readers to the releases page for a supported version. Retraction in Go is a machine-readable warning that surfaces during dependency resolution, so a downstream build that still names a withdrawn tag gets told rather than silently installing it. The module path is github.com/cohesion-org/deepseek-go, and the direct dependencies are deliberately few: a dotenv loader, the Ollama client, and the testify assertion library, with the rest pulled in as indirect test and serialization helpers. The source layout is flat and file-per-concern, with separate files for chat, streaming, fill-in-the-middle, balance, models, JSON handling, Ollama, image calls, and the Anthropic-compatible surface, each paired with its own test file. Request and response handling are split into their own files, with dedicated payload and mapper files translating between SDK types and the wire format, while an internal directory and a utils directory hold shared helpers. A checked-in env.example sits beside the module file, so the expected environment variable names are visible without reading the source.

Editorial conclusion

deepseek-go suits Go services that want typed access to the DeepSeek V4 models without hand-rolling HTTP, and teams that need the thinking and strict-tool-call switches exposed as ordinary struct fields. It is a weaker fit if you want one abstraction over many non-OpenAI-shaped providers, because the override path assumes the provider mimics the Azure or OpenRouter request shape. Before adopting it, read the deprecation dates for deepseek-chat and deepseek-reasoner and migrate off those names, confirm your Go toolchain matches the declared version, and check the retractions so you do not pin a release the maintainers withdrew.

Frequently asked questions

Official sources

1. cohesion-org/deepseek-go on GitHub
2. Issues
3. License: MIT
4. README
5. Releases