### Frontend Development (WebUI) Setup

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/CONTRIBUTING.en.md

Steps to install dependencies and start the development server for the WebUI.

```bash
# 1. Navigate to WebUI directory
cd webui

# 2. Install dependencies
npm ci

# 3. Start dev server (hot reload)
npm run dev
# Default: http://localhost:5173, auto-proxies API to backend
# host: 0.0.0.0 is not configured, so LAN access is not enabled by default
```

--------------------------------

### Local Run - Clone and Setup

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Steps to clone the repository, copy and edit the configuration file, and start the local server.

```bash
# Clone
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# Copy and edit config
cp config.example.json config.json
# Open config.json and fill in:
#   - keys: your API access keys
#   - accounts: DeepSeek accounts (email or mobile + password)

# Start
go run ./cmd/ds2api
```

--------------------------------

### Docker Development Setup

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/CONTRIBUTING.en.md

Command to start development services using Docker Compose.

```bash
docker-compose -f docker-compose.dev.yml up
```

--------------------------------

### Configure and Start

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Steps to download, extract, configure, and start the DS2API release binaries.

```bash
# 1. Download the archive for your platform
# 2. Extract
tar -xzf ds2api_<tag>_linux_amd64.tar.gz
cd ds2api_<tag>_linux_amd64

# 3. Configure
cp config.example.json config.json
# Edit config.json

# 4. Start
./ds2api
```

--------------------------------

### Backend Development Setup

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/CONTRIBUTING.en.md

Steps to clone the repository, configure the backend, and run the Go application.

```bash
# 1. Clone
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# 2. Configure
cp config.example.json config.json
# Edit config.json with test accounts

# 3. Run backend
go run ./cmd/ds2api
# Local access: http://127.0.0.1:5001
# Actual bind: 0.0.0.0:5001, so LAN access is available via your private IP
```

--------------------------------

### Unit Tests Quick Start

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/TESTING.md

Command to run all unit tests.

```bash
./tests/scripts/run-unit-all.sh
```

--------------------------------

### Output Directory Error Example

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Example of an output directory error during Vercel deployment.

```text
No Output Directory named "public" found after the Build completed.
```

--------------------------------

### CLI Flags Example

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/TESTING.md

Example of running the DS2API test suite with various CLI flags.

```bash
go run ./cmd/ds2api-tests \
  --config config.json \
  --admin-key admin \
  --out artifacts/testsuite \
  --port 0 \
  --timeout 120 \
  --retries 2 \
  --no-preflight=false \
  --keep 5
```

--------------------------------

### Go Build Failure Example

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Example of a Go build failure error message encountered during Vercel deployment.

```text
Error: Command failed: go build -ldflags -s -w -o .../bootstrap ...
```

--------------------------------

### End-to-End Tests Quick Start

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/TESTING.md

Command to run end-to-end tests.

```bash
./tests/scripts/run-live.sh
```

--------------------------------

### Unit Tests Quick Start (Split by Language)

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/TESTING.md

Commands to run unit tests separately for Go and Node.

```bash
# or run by language separately
./tests/scripts/run-unit-go.sh
./tests/scripts/run-unit-node.sh
```

--------------------------------

### Configuration Best Practice Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.en.md

This snippet shows how to copy the example configuration file to be used as the main configuration.

```bash
cp config.example.json config.json
```

--------------------------------

### Universal First Step: Copy Example Config

Source: https://github.com/cjackhwang/ds2api/blob/main/README.en.md

Command to copy the example configuration file to a usable configuration file.

```bash
cp config.example.json config.json
# Edit config.json
```

--------------------------------

### Release Package Usage Steps

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.md

Steps to download, extract, configure, and start DS2API from a release package.

```bash
# 1. Download the appropriate platform compressed package
# 2. Unzip
tar -xzf ds2api_<tag>_linux_amd64.tar.gz
cd ds2api_<tag>_linux_amd4

# 3. Configure
cp config.example.json config.json
# Edit config.json

# 4. Start
./ds2api
```

--------------------------------

### Local Development: Clone and Run

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.md

Basic steps to clone the ds2api repository and start the service locally.

```bash
# 克隆仓库
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# 复制并编辑配置
cp config.example.json config.json
# 使用你喜欢的编辑器打开 config.json，填入：
#   - keys: 你的 API 访问密钥
#   - accounts: DeepSeek 账号（email 或 mobile + password）

# 启动服务
go run ./cmd/ds2api
```

--------------------------------

### Admin Settings Response

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example structure of the response from GET /admin/settings.

```json
{
  "success": true,
  "admin": {"has_password_hash": true, "jwt_expire_hours": 24, "jwt_valid_after_unix": 1738400000, "default_password_warning": false},
  "runtime": {"account_max_inflight": 10, "account_max_queue": 100, "global_max_inflight": 100, "token_refresh_interval_hours": 12},
  "responses": {"store_ttl_seconds": 86400},
  "embeddings": {"provider": "deepseek"},
  "auto_delete": {"mode": "none"},
  "current_input_file": {"enabled": true, "min_chars": 10},
  "thinking_injection": {"enabled": true, "prompt": "", "default_prompt": "请思考后回答"},
  "model_aliases": {
    "claude-sonnet-4-6": "deepseek-v4-flash",
    "claude-opus-4-6": "deepseek-v4-pro"
  },
  "env_backed": false,
  "needs_vercel_sync": false
}
```

--------------------------------

### Linux systemd Service - Installation

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Commands to copy the compiled binary and related files to the target directory for systemd service installation.

```bash
# Copy compiled binary and related files to target directory
sudo mkdir -p /opt/ds2api
sudo cp ds2api config.json /opt/ds2api/
sudo cp -r static/admin /opt/ds2api/static/admin
```

--------------------------------

### Admin API Settings Response Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.en.md

Example JSON response for the GET /admin/settings endpoint, showing runtime settings and status.

```json
{
  "success": true,
  "admin": {"has_password_hash": true, "jwt_expire_hours": 24, "jwt_valid_after_unix": 1738400000, "default_password_warning": false},
  "runtime": {"account_max_inflight": 10, "account_max_queue": 100, "global_max_inflight": 100, "token_refresh_interval_hours": 12},
  "responses": {"store_ttl_seconds": 3600},
  "embeddings": {"provider": "openai"},
  "auto_delete": {"mode": "single"},
  "current_input_file": {"enabled": true, "min_chars": 10},
  "thinking_injection": {"enabled": true, "prompt": "Think step by step.", "default_prompt": "Think step by step.", "max_tokens": 100},
  "model_aliases": {"claude-sonnet-4-6": "deepseek-v4-flash", "claude-opus-4-6": "deepseek-v4-pro"},
  "env_backed": false,
  "needs_vercel_sync": false
}
```

--------------------------------

### Run Unit Tests for Specific Modules

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/TESTING.md

Examples of running unit tests for specific Go modules.

```go
# Run tests related to tool calls (recommended for debugging tool call parsing issues)
go test -v -run 'TestParseToolCalls|TestProcessToolSieve|TestRepair' ./internal/toolcall ./internal/toolstream

# Run a single test case
go test -v -run TestParseToolCallsAllowsAllEmptyParameterPayload ./internal/toolcall

# Run format related tests
go test -v ./internal/format/...

# Run HTTP API related tests
go test -v ./internal/httpapi/openai/...
```

--------------------------------

### Test API Call

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Example of how to test the API call using curl.

```bash
curl http://127.0.0.1:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hello"}]}'
```

--------------------------------

### Docker Compose Deployment

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Steps to pull the DS2API Docker image, configure environment variables, and start the service using Docker Compose.

```bash
# Pull prebuilt image
docker pull ghcr.io/cjackhwang/ds2api:latest

# Copy env template and config file
cp .env.example .env
cp config.example.json config.json

# Edit .env and set at least:
#   DS2API_ADMIN_KEY=your-admin-key
# Optionally set the host port:
#   DS2API_HOST_PORT=6011

# Start
docker-compose up -d
```

--------------------------------

### Local Run - Start

Source: https://github.com/cjackhwang/ds2api/blob/main/README.en.md

Starts the ds2api server locally.

```bash
go run ./cmd/ds2api
```

--------------------------------

### Admin Login

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example of logging into the admin interface.

```bash
curl http://localhost:5001/admin/login \
  -H "Content-Type: application/json" \
  -d '{"admin_key": "admin"}'
```

--------------------------------

### Linux systemd Service - Service File

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Example systemd service file for DS2API.

```ini
# /etc/systemd/system/ds2api.service

[Unit]
Description=DS2API (Go)
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/ds2api
Environment=PORT=5001
Environment=DS2API_CONFIG_PATH=/opt/ds2api/config.json
Environment=DS2API_ADMIN_KEY=your-admin-key-here
ExecStart=/opt/ds2api/ds2api
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Configuration File Copy

Source: https://github.com/cjackhwang/ds2api/blob/main/README.MD

Copying the example configuration file to be edited.

```bash
cp config.example.json config.json
# 编辑 config.json
```

--------------------------------

### POST /admin/dev/raw-samples/save - Example Selectors

Source: https://github.com/cjackhwang/ds2api/blob/main/API.en.md

Examples of selectors that can be used to persist an in-memory capture chain.

```json
{"chain_key":"session:xxxx","sample_id":"tmp-from-memory"}
```

```json
{"capture_id":"cap_xxx","sample_id":"tmp-from-memory"}
```

```json
{"query":"Guangzhou weather","sample_id":"tmp-from-memory"}
```

--------------------------------

### Build WebUI

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/CONTRIBUTING.en.md

Command to manually build the WebUI assets.

```bash
./scripts/build-webui.sh
```

--------------------------------

### cURL Example: OpenAI with Search

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example cURL command for making a chat completion request with search enabled to the OpenAI compatible API.

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-search",
    "messages": [{"role": "user", "content": "今天的新闻"}],
    "stream": true
  }'
```

--------------------------------

### Specific Account Request

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example of making a request to a specific account.

```bash
curl http://localhost:5001/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Ds2-Target-Account: user@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

--------------------------------

### GET /anthropic/v1/models - Response Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example JSON response for listing available models.

```json
{
  "object": "list",
  "data": [
    {"id": "claude-sonnet-4-6", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-sonnet-4-6-nothinking", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-haiku-4-5", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-haiku-4-5-nothinking", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-opus-4-6", "object": "model", "created": 1715635200, "owned_by": "anthropic"},
    {"id": "claude-opus-4-6-nothinking", "object": "model", "created": 1715635200, "owned_by": "anthropic"}
  ],
  "first_id": "claude-opus-4-6",
  "last_id": "claude-3-haiku-20240307-nothinking",
  "has_more": false
}
```

--------------------------------

### Internal Package Import Error Example

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Example of an internal package import error during Vercel deployment.

```text
use of internal package ds2api/internal/server not allowed
```

--------------------------------

### Local Run - Configure

Source: https://github.com/cjackhwang/ds2api/blob/main/README.en.md

Copies the example configuration file and prompts the user to edit it.

```bash
cp config.example.json config.json
# Edit config.json with your DeepSeek account info and API keys
```

--------------------------------

### Local Run - WebUI Build (Manual)

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Manual steps to build the WebUI from source.

```bash
./scripts/build-webui.sh
```

```bash
cd webui
npm ci
npm run build
# Output goes to static/admin/
```

--------------------------------

### Option 1: Download Release Binaries - Extract and Run

Source: https://github.com/cjackhwang/ds2api/blob/main/README.en.md

Steps to download, extract, and run the release binaries.

```bash
# After downloading the archive for your platform
tar -xzf ds2api_<tag>_linux_amd64.tar.gz
cd ds2api_<tag>_linux_amd64
cp config.example.json config.json
# Edit config.json
./ds2api
```

--------------------------------

### Run All Sample Directories with Token Alignment

Source: https://github.com/cjackhwang/ds2api/blob/main/tests/raw_stream_samples/README.md

Iterates through all sample directories, runs the SSE simulator for each, and prints token alignment results. The --fail-on-token-mismatch flag can be added to treat token mismatches as failures.

```bash
for d in tests/raw_stream_samples/*; do
  [ -d "$d" ] || continue
  sid="$(basename "$d")"
  [ -f "$d/upstream.stream.sse" ] || continue
  node tests/tools/deepseek-sse-simulator.mjs --samples-root tests/raw_stream_samples --sample-id "$sid"
done
```

--------------------------------

### Chat History Read-Only File System Error Example

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.md

Example error message when chat history cannot be created due to a read-only file system on Vercel.

```text
create chat history dir: mkdir /var/task/data: read-only file system
```

--------------------------------

### Admin Export Config Response

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example structure of the response from GET /admin/config/export.

```json
{
  "config": {
    "keys": ["k1", "k2"],
    "api_keys": [
      {"key": "k1", "name": "主 Key", "remark": "生产流量"},
      {"key": "k2", "name": "备用 Key", "remark": "压测"}
    ],
    "accounts": [
      {
        "identifier": "user@example.com",
        "email": "user@example.com",
        "mobile": "",
        "has_password": true,
        "has_token": true,
        "token_preview": "abcde..."
      }
    ],
    "model_aliases": {
      "claude-sonnet-4-6": "deepseek-v4-flash",
      "claude-opus-4-6": "deepseek-v4-pro"
    }
  },
  "json": "{\"keys\": [\"k1\", \"k2\"], \"api_keys\": [{\"key\": \"k1\", \"name\": \"主 Key\", \"remark\": \"生产流量\"}, {\"key\": \"k2\", \"name\": \"备用 Key\", \"remark\": \"压测\"}], \"accounts\": [{\"identifier\": \"user@example.com\", \"email\": \"user@example.com\", \"mobile\": \"\", \"has_password\": true, \"has_token\": true, \"token_preview\": \"abcde...\"}], \"model_aliases\": {\"claude-sonnet-4-6\": \"deepseek-v4-flash\", \"claude-opus-4-6\": \"deepseek-v4-pro\"}}",
  "base64": "eyJzb21lIjoiaW5mbyJ9"
}
```

--------------------------------

### Compile to Binary

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Command to compile the Go project into an executable binary.

```bash
go build -o ds2api ./cmd/ds2api
./ds2api
```

--------------------------------

### Health Check configuration

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Example health check configuration for a Docker service.

```yaml
healthcheck:
  test: ["CMD", "/usr/local/bin/busybox", "wget", "-qO-", "http://localhost:${PORT:-5001}/healthz"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s
```

--------------------------------

### Get Accounts Response

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example response for listing accounts, including pagination and filtering parameters.

```json
{
  "items": [
    {
      "identifier": "user@example.com",
      "email": "user@example.com",
      "mobile": "",
      "has_password": true,
      "has_token": true,
      "token_preview": "abc...",
      "test_status": "ok"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 10,
  "total_pages": 3
}
```

--------------------------------

### Run All Canonical Samples

Source: https://github.com/cjackhwang/ds2api/blob/main/tests/raw_stream_samples/README.md

Executes all default samples specified in manifest.json.

```bash
./tests/scripts/run-raw-stream-sim.sh
```

--------------------------------

### Zeabur One-Click Deployment

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Link to deploy DS2API on Zeabur using a Dockerfile.

```markdown
[![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/templates/L4CFHP)
```

--------------------------------

### List Models Endpoint Response

Source: https://github.com/cjackhwang/ds2api/blob/main/API.en.md

Example JSON response for the GET /v1/models endpoint, listing supported DeepSeek native models.

```json
{
  "object": "list",
  "data": [
    {"id": "deepseek-v4-flash", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-flash-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-pro", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-pro-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-flash-search", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-flash-search-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-pro-search", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-pro-search-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-vision", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []},
    {"id": "deepseek-v4-vision-nothinking", "object": "model", "created": 1677610602, "owned_by": "deepseek", "permission": []}
  ]
}
```

--------------------------------

### Optional Vercel Sync Environment Variables

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Optional environment variables for enabling WebUI one-click Vercel sync.

```text
VERCEL_TOKEN=your-vercel-token
VERCEL_PROJECT_ID=prj_xxxxxxxxxxxx
VERCEL_TEAM_ID=team_xxxxxxxxxxxx   # optional for personal accounts
```

--------------------------------

### Create Account

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Creates a new account with email and password.

```json
{"email": "user@example.com", "password": "pwd"}
```

--------------------------------

### POST /anthropic/v1/messages/count_tokens - Response Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example JSON response for token count.

```json
{
  "input_tokens": 5
}
```

--------------------------------

### Running Tests

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/CONTRIBUTING.en.md

Commands for running local PR gates and end-to-end live tests.

```bash
# Local PR gates (kept aligned with the quality-gates workflow)
./scripts/lint.sh
./tests/scripts/check-refactor-line-gate.sh
./tests/scripts/run-unit-all.sh
npm run build --prefix webui

# End-to-end live tests (real accounts; recommended for releases or high-risk changes)
./tests/scripts/run-live.sh
```

--------------------------------

### POST /anthropic/v1/messages/count_tokens - Request Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example JSON request for counting tokens.

```json
{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}
```

--------------------------------

### Vercel Architecture Diagram

Source: https://github.com/cjackhwang/ds2api/blob/main/docs/DEPLOY.en.md

Illustrates the routing and runtime separation for Go and Node.js on Vercel.

```text
Request ──────┐
              │
              ▼
         vercel.json routing
              │
        ┌─────┴─────┐
        │           │
        ▼           ▼
  api/index.go   api/chat-stream.js
  (Go Runtime)   (Node Runtime)
```

--------------------------------

### POST /anthropic/v1/messages - Non-streaming Response Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example JSON response for a non-streaming message.

```json
{
  "id": "msg_1738400000000000000",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "回复内容"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 34
  }
}
```

--------------------------------

### POST /anthropic/v1/messages - Request Headers Example

Source: https://github.com/cjackhwang/ds2api/blob/main/API.md

Example HTTP headers for the messages endpoint.

```http
x-api-key: your-api-key
Content-Type: application/json
anthropic-version: 2023-06-01
```