概述

DeepShield 提供完全兼容 OpenAI 的 API 接口，支持流式和非流式响应、自动故障切换和 Token 用量统计。只需将 base_url 指向 DeepShield 服务器即可使用。

  • Base URL：https://api.deepshields.com/v1
  • 主要端点：POST https://api.deepshields.com/v1/chat/completions
  • 模型列表：GET https://api.deepshields.com/v1/models
  • 健康检查：GET https://api.deepshields.com/health

认证

所有 API 请求需要通过 Bearer Token 认证。在 HTTP 请求头中添加：

HTTP
Authorization: Bearer YOUR_API_KEY

API Key 可以在对话页面点击左下角用户名查看。注册用户将自动分配一个唯一的 API Key。

Chat Completions

创建一个聊天补全请求。

请求

HTTP
POST /v1/chat/completions
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求体参数

参数类型必填说明
modelstring是模型名称：chat（对话）、reasoner（推理）
messagesarray是消息列表，每条包含 role 和 content
streamboolean否是否使用流式响应，默认 false
temperaturenumber否采样温度 0-2，默认 1
max_tokensinteger否最大生成 token 数

请求示例

JSON
{
  "model": "chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false
}

响应示例

JSON
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

流式响应

将 stream 设置为 true 启用 Server-Sent Events (SSE) 流式响应。每个事件以 data: 前缀发送，最后以 data: [DONE] 结束。

JSON (SSE chunk)
data: {
  "id": "chatcmpl-xxx",
  "object": "chat.completion.chunk",
  "choices": [
    {
      "index": 0,
      "delta": {"content": "Hello"},
      "finish_reason": null
    }
  ]
}

data: [DONE]

错误处理

API 使用标准 HTTP 状态码。错误响应格式：

JSON
{
  "error": {
    "message": "invalid API key",
    "type": "authentication_error"
  }
}
状态码说明
400请求参数无效
401认证失败（API Key 无效或缺失）
429请求过于频繁（匿名用户限制）
502上游服务不可用

Python SDK

使用官方 openai Python SDK：

BASH
pip install openai

非流式调用

PYTHON
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepshields.com/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="chat",
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
)
print(response.choices[0].message.content)

流式调用

PYTHON
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepshields.com/v1",
    api_key="YOUR_API_KEY",
)

stream = client.chat.completions.create(
    model="chat",
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript SDK

BASH
npm install openai
JAVASCRIPT
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: "https://api.deepshields.com/v1",
    apiKey: "YOUR_API_KEY",
});

const response = await client.chat.completions.create({
    model: "chat",
    messages: [
        { role: "user", content: "Hello!" }
    ],
});
console.log(response.choices[0].message.content);

cURL

BASH
curl -X POST https://api.deepshields.com/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d "{\"model\":\"chat\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}]}"

快速体验（可直接复制执行）

登录后，以下示例中的 YOUR_API_KEY 会自动替换为你的 API Key，可直接复制到终端运行，也可点击"执行"在线测试：

基础对话

BASH
curl -X POST https://api.deepshields.com/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d "{\"model\":\"chat\",\"messages\":[{\"role\":\"user\",\"content\":\"你好，请介绍一下你自己\"}]}"

流式输出（SSE）

BASH
curl -X POST https://api.deepshields.com/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -N -d "{\"model\":\"chat\",\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"用三句话解释什么是大语言模型\"}]}"

多轮对话

BASH
curl -X POST https://api.deepshields.com/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d "{\"model\":\"chat\",\"messages\":[{\"role\":\"system\",\"content\":\"你是一个网络安全专家\"},{\"role\":\"user\",\"content\":\"什么是SQL注入？\"},{\"role\":\"assistant\",\"content\":\"SQL注入是一种常见的Web安全漏洞...\"},{\"role\":\"user\",\"content\":\"如何防御？\"}]}"

使用推理模型

BASH
curl -X POST https://api.deepshields.com/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d "{\"model\":\"reasoner\",\"messages\":[{\"role\":\"user\",\"content\":\"分析一段可疑的网络流量日志，判断是否存在DDoS攻击特征\"}]}"