home / skills / vm0-ai / vm0-skills / deepseek

deepseek skill

safe

This skill enables chat, reasoning, and code generation with DeepSeek's OpenAI-compatible API, simplifying integration and cost-effective AI workflows.

npx playbooks add skill vm0-ai/vm0-skills --skill deepseek

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

9.7 KB

---
name: deepseek
description: DeepSeek AI large language model API via curl. Use this skill for chat completions, reasoning, and code generation with OpenAI-compatible endpoints.
vm0_secrets:
  - DEEPSEEK_API_KEY
---

# DeepSeek API

Use the DeepSeek API via direct `curl` calls to access **powerful AI language models** for chat, reasoning, and code generation.

> Official docs: `https://api-docs.deepseek.com/`

---

## When to Use

Use this skill when you need to:

- **Chat completions** with DeepSeek-V3.2 model
- **Deep reasoning** tasks using the reasoning model
- **Code generation and completion** (FIM - Fill-in-the-Middle)
- **OpenAI-compatible API** as a cost-effective alternative

---

## Prerequisites

1. Sign up at [DeepSeek Platform](https://platform.deepseek.com/) and create an account
2. Go to [API Keys](https://platform.deepseek.com/api_keys) and generate a new API key
3. Top up your balance (no free tier, but very affordable pricing)

```bash
export DEEPSEEK_API_KEY="your-api-key"
```

### Pricing (per 1M tokens)

| Type | Price |
|------|-------|
| Input (cache hit) | $0.028 |
| Input (cache miss) | $0.28 |
| Output | $0.42 |

### Rate Limits

DeepSeek does **not** enforce strict rate limits. They will try to serve every request. During high traffic, connections are maintained with keep-alive signals.

---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

## How to Use

All examples below assume you have `DEEPSEEK_API_KEY` set.

The base URL for the DeepSeek API is:

- `https://api.deepseek.com` (recommended)
- `https://api.deepseek.com/v1` (OpenAI-compatible)

---

### 1. Basic Chat Completion

Send a simple chat message:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, who are you?"
    }
  ]
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json'
```

**Available models:**

- `deepseek-chat`: DeepSeek-V3.2 non-thinking mode (128K context, 8K max output)
- `deepseek-reasoner`: DeepSeek-V3.2 thinking mode (128K context, 64K max output)

---

### 2. Chat with Temperature Control

Adjust creativity/randomness with temperature:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "Write a short poem about coding."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 200
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json' | jq -r '.choices[0].message.content'
```

**Parameters:**

- `temperature` (0-2, default 1): Higher = more creative, lower = more deterministic
- `top_p` (0-1, default 1): Nucleus sampling threshold
- `max_tokens`: Maximum tokens to generate

---

### 3. Streaming Response

Get real-time token-by-token output:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in simple terms."
    }
  ],
  "stream": true
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json'
```

Streaming returns Server-Sent Events (SSE) with delta chunks, ending with `data: [DONE]`.

---

### 4. Deep Reasoning (Thinking Mode)

Use the reasoner model for complex reasoning tasks:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-reasoner",
  "messages": [
    {
      "role": "user",
      "content": "What is 15 * 17? Show your work."
    }
  ]
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json' | jq -r '.choices[0].message.content'
```

The reasoner model excels at math, logic, and multi-step problems.

---

### 5. JSON Output Mode

Force the model to return valid JSON:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "system",
      "content": "You are a JSON generator. Always respond with valid JSON."
    },
    {
      "role": "user",
      "content": "List 3 programming languages with their main use cases."
    }
  ],
  "response_format": {
    "type": "json_object"
  }
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json' | jq -r '.choices[0].message.content'
```

---

### 6. Multi-turn Conversation

Continue a conversation with message history:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "My name is Alice."
    },
    {
      "role": "assistant",
      "content": "Nice to meet you, Alice."
    },
    {
      "role": "user",
      "content": "What is my name?"
    }
  ]
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json' | jq -r '.choices[0].message.content'
```

---

### 7. Code Completion (FIM)

Use Fill-in-the-Middle for code completion (beta endpoint):

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "prompt": "def add(a, b):\n ",
  "max_tokens": 20
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/beta/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json' | jq -r '.choices[0].text'
```

FIM is useful for:
- Code completion in editors
- Filling gaps in documents
- Context-aware text generation

---

### 8. Function Calling (Tools)

Define functions the model can call:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Tokyo?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city name"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json'
```

The model will return a `tool_calls` array when it wants to use a function.

---

### 9. Check Token Usage

Extract usage information from response:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json' | jq '.usage'
```

Response includes:
- `prompt_tokens`: Input token count
- `completion_tokens`: Output token count
- `total_tokens`: Sum of both

---

## OpenAI SDK Compatibility

DeepSeek is fully compatible with OpenAI SDKs. Just change the base URL:

**Python:**
```python
from openai import OpenAI
client = OpenAI(api_key="your-deepseek-key", base_url="https://api.deepseek.com")
```

**Node.js:**
```javascript
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: 'your-deepseek-key', baseURL: 'https://api.deepseek.com' });
```

---

## Tips: Complex JSON Payloads

For complex requests with nested JSON (like function calling), use a temp file to avoid shell escaping issues:

Write to `/tmp/deepseek_request.json`:

```json
{
  "model": "deepseek-chat",
  "messages": [{"role": "user", "content": "What is the weather in Tokyo?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }
  }]
}
```

Then run:

```bash
bash -c 'curl -s "https://api.deepseek.com/chat/completions" -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" -d @/tmp/deepseek_request.json'
```

---

## Guidelines

1. **Choose the right model**: Use `deepseek-chat` for general tasks, `deepseek-reasoner` for complex reasoning
2. **Use caching**: Repeated prompts with same prefix benefit from cache pricing ($0.028 vs $0.28)
3. **Set max_tokens**: Prevent runaway generation by setting appropriate limits
4. **Use streaming for long responses**: Better UX for real-time applications
5. **JSON mode requires system prompt**: When using `response_format`, include JSON instructions in system message
6. **FIM uses beta endpoint**: Code completion endpoint is at `api.deepseek.com/beta`
7. **Complex JSON**: Use temp files with `-d @filename` to avoid shell quoting issues

Overview

This skill provides curl-based access to DeepSeek AI models for chat, deep reasoning, and code generation using OpenAI-compatible endpoints. It focuses on practical shell examples, streaming, function/tool calls, JSON output, and Fill-in-the-Middle (FIM) code completion. Use it to integrate DeepSeek into scripts, CI pipelines, or local tooling with minimal setup.

How this skill works

The skill shows concrete curl requests against https://api.deepseek.com (and the OpenAI-compatible /v1 path). It demonstrates building JSON payloads in temp files, setting the DEEPSEEK_API_KEY environment variable, and parsing responses with tools like jq. Examples cover chat completions, a reasoning-specific model, streaming SSE responses, FIM code completions on the beta endpoint, and function/tool calling patterns.

When to use it

When you need chat-style conversational completions from DeepSeek models
For multi-step or math-heavy reasoning using the reasoner model
When generating or completing code, including Fill-in-the-Middle scenarios
When you want OpenAI SDK compatibility but prefer DeepSeek’s pricing or models
When you need streaming token-by-token output for live UIs

Best practices

Store API key in DEEPSEEK_API_KEY and never inline secrets in scripts
Write complex request JSON to a temporary file and use curl -d @/tmp/file to avoid shell quoting issues
Choose deepseek-chat for general tasks and deepseek-reasoner for logic/multi-step problems
Set max_tokens and temperature to control output length and creativity
Use streaming for long outputs and check usage fields to monitor token costs
Wrap curl calls that use $VAR in bash -c '...' when piping to avoid environment variable clearing issues

Example use cases

Quickly prototype a chatbot via shell scripts or cron jobs using chat/completions
Run deterministic math or logic checks with deepseek-reasoner and extract step-by-step work
Integrate FIM code completion into an editor plugin by calling the beta completions endpoint
Return strict JSON from the model for downstream parsing by setting response_format and a system JSON instruction
Implement function/tool calling: let the model request external data and inspect tool_calls in the response

FAQ

Do I need an OpenAI SDK to use DeepSeek?

No. You can call DeepSeek directly via curl, but it’s also OpenAI-compatible: set base_url to https://api.deepseek.com in existing OpenAI SDKs.

How do I avoid shell quoting problems with complex JSON?

Write the JSON to a temporary file and pass it to curl with -d @/tmp/request.json; this avoids escaping issues.

Which model should I pick for heavy reasoning?

Use deepseek-reasoner for multi-step math, logic, and complex reasoning; use deepseek-chat for general conversation and code generation.