deepseek-php-client

DeepSeek PHP Client

⚡️ A community-driven, open-source PHP client for DeepSeek AI, officially listed in the DeepSeek API documentation and built for expressive, production-ready AI integrations.

AR | CN

Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
  • Basic Usage
  • Advanced Configuration
  • important warning with json mode
  • Use with Symfony HttpClient
  • Get Models List
  • Function Calling
  • Framework Integration
• 🆕 Migration Guide
• 📝 Changelog
• 🧪 Testing
• 🔒 Security
• 📄 License

---

✨ Features

• Seamless API Integration: PHP-first interface for DeepSeek’s AI capabilities.
• Fluent Builder Pattern: Chainable methods for intuitive request building.
• Enterprise Ready: PSR-18 compliant HTTP client integration.
• Latest DeepSeek V4 Models: First-class support for deepseek-v4-pro and deepseek-v4-flash with 1M-token context windows and thinking / non-thinking modes.
• Streaming Ready: Built-in support for real-time response handling.
• Many Http Clients: easy to use Guzzle http client (default) , or symfony http client.
• Framework Friendly: Laravel & Symfony packages available.

Supported Models

• Models::V4_PRO — flagship 1.6T/49B-active model, max 384K output tokens.
• Models::V4_FLASH — fast, economical 284B/13B-active model, max 384K output tokens.

Legacy Models::CHAT, Models::CODER, Models::R1, and Models::R1Zero are deprecated and will be removed in v3.0.0. The deepseek-chat and deepseek-reasoner aliases retire from the DeepSeek API on 2026-07-24.

---

📦 Installation

Require the package via Composer:

composer require deepseek-php/deepseek-php-client

Requirements:

• PHP 8.1+

---

🚀 Quick Start

Basic Usage

Get started with just two lines of code:

use DeepSeek\DeepSeekClient;

$response = DeepSeekClient::build('your-api-key')
    ->query('Explain quantum computing in simple terms')
    ->run();

echo $response;

📌 Defaults used:

• Model: API default (no model field sent unless you call withModel())
• Temperature: 1.3 (TemperatureValues::GENERAL_CONVERSATION)
• Max tokens: 4096
• Response format: text

Advanced Configuration

use DeepSeek\DeepSeekClient;
use DeepSeek\Enums\Models;

$client = DeepSeekClient::build(apiKey:'your-api-key', baseUrl:'https://api.deepseek.com', timeout:30, clientType:'guzzle');

$response = $client
    ->withModel(Models::V4_PRO->value)
    ->withStream()
    ->setTemperature(1.2)
    ->setMaxTokens(8192)
    ->setResponseFormat('text') // or "json_object"  with careful .
    ->query('Explain quantum computing in simple terms')
    ->run();

echo 'API Response:'.$response;

⚠️ DeepSeek JSON Mode Requirement

When using:

->setResponseFormat('json_object')

Your prompt must contain the word "json" in some form. Otherwise, the API will reject the request with the following error:

"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"

---

🚫 Incorrect Usage

->setResponseFormat('json_object')
->query('Explain quantum computing in simple terms')

✅ Correct Usage

->setResponseFormat('json_object')
->query('Respond in valid JSON format. Explain quantum computing in simple terms.')

✅ Tip: For best results, also provide a JSON example or explicitly say: “Respond only in valid JSON.”

---

Use with Symfony HttpClient

the package already built with symfony Http client, if you need to use package with symfony Http Client , it is easy to achieve that, just pass clientType:'symfony' with build function.

ex with symfony:

//  with defaults baseUrl and timeout
$client = DeepSeekClient::build('your-api-key', clientType:'symfony')
// with customization
$client = DeepSeekClient::build(apiKey:'your-api-key', baseUrl:'https://api.deepseek.com', timeout:30, clientType:'symfony');

$client->query('Explain quantum computing in simple terms')
       ->run();

Get Models List

use DeepSeek\DeepSeekClient;

$response = DeepSeekClient::build('your-api-key')
    ->getModelsList()
    ->run();

echo $response;
// {
//   "object": "list",
//   "data": [
//     {"id": "deepseek-v4-pro",   "object": "model", "owned_by": "deepseek"},
//     {"id": "deepseek-v4-flash", "object": "model", "owned_by": "deepseek"},
//     {"id": "deepseek-chat",     "object": "model", "owned_by": "deepseek"},     // deprecated, retires 2026-07-24
//     {"id": "deepseek-reasoner", "object": "model", "owned_by": "deepseek"}      // deprecated, retires 2026-07-24
//   ]
// }

Function Calling

Function Calling allows the model to call external tools to enhance its capabilities.[1]

You Can check the documentation for function calling in FUNCTION-CALLING.md

🛠 Framework Integration

Laravel Deepseek Package

---

🚧 Migration Guide

Upgrading from v1.x? Check our comprehensive Migration Guide for breaking changes and upgrade instructions.

---

📝 Changelog

Detailed release notes available in CHANGELOG.md

---

🧪 Testing

./vendor/bin/pest

Test coverage coming in v2.1.

---

---

🔒 Security

Report Vulnerabilities: to [email protected]

---

📄 License

This package is open-source software licensed under the MIT License.