科普文：AI时代的程序员【DeepSeek API 请求参数和API调用说明】

概叙

DeepSeek API是一个用于与DeepSeek模型进行交互的接口，它允许客户端发送请求并接收模型的响应。

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ARK_API_KEY>" \
  -d '{
    "model": "<Model ID>",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "中国的全称和简介"
        }
    ]
  }'

要调用 DeepSeek 的 API，通常需要以下步骤：

1. 获取 API 密钥

首先，你需要在 DeepSeek 平台上注册并获取 API 密钥。这个密钥用于验证你的身份并授权你访问 API。

获取 API Key: 访问 DeepSeek 的官方平台（https://platform.deepseek.com），注册并登录后申请 API Key。
安全性: API Key 是敏感信息，勿在客户端代码中硬编码或公开。

2. 阅读 API 文档

DeepSeek 通常会提供详细的 API 文档，包含可用的端点、请求参数、响应格式等信息。确保你熟悉这些内容。

3. 设置请求

根据 API 文档，设置 HTTP 请求。通常包括：

URL: API 端点的 URL。
Headers: 包含 API 密钥和其他必要信息。
Body: 请求参数，通常是 JSON 格式。

3.1 请求头参数

Content-Type: 指定请求体的内容格式。通常为 application/json，表示请求体是 JSON 格式。
Authorization: 用于身份验证，格式为 Bearer <DeepSeek API Key>，其中 <DeepSeek API Key> 是你在 DeepSeek 平台申请的 API 密钥。

3.2 请求体参数（必选参数）

model: 指定使用的模型。例如：
- deepseek-chat: 表示使用 DeepSeek 的对话模型，适合对话生成任务。
- 其他模型（如 deepseek-coder）可能适用于代码生成或特定任务。
messages:这是一个数组，用于定义对话内容。每个消息对象包含以下字段：
- role: 指定消息的角色，可能值为：
  - system: 设置对话的上下文或指示（如“您是帮助用户的助手”）。
  - user: 用户输入的内容（如“Hello!”）。
  - assistant: 模型的回复（通常由 API 自动生成，不需要手动设置）。
- content: 消息的具体内容。
stream: 是否启用流式传输。默认为 false，表示不启用流式传输。如果设置为 true，API 会实时返回生成内容，适合需要实时Interaction的场景。

3.3 完整参数说明

{
  "messages": [
    {
      "role": "system",
      "content": "智能助手"
    },
    {
      "role": "user",
      "content": "中国的全称和简介"
    }
  ],
  "model": "deepseek-chat",
  "stream": false,
  "max_tokens": 512,
  "stop": ["null"],
  "temperature": 0.7,
  "top_p": 0.7,
  "top_k": 50,
  "frequency_penalty": 0.5,
  "n": 1,
  "response_format": {
    "type": "text"
  },
  "tools": [
    {
      "type": "function",
      "function": {
        "description": "<string>",
        "name": "<string>",
        "parameters": {},
        "strict": false
      }
    }
  ]
}

以上示例展示了如何构建一个包含多种可选参数的请求体，以调用DeepSeek-Chat API。请注意，具体参数和格式可能会根据DeepSeek平台的更新而有所变化，因此在实际使用前，请务必参考最新的API文档。

必需参数

‌messages‌:
- 类型：数组
- 描述：包含对话消息列表的数组，至少包含一条消息。每条消息都是一个对象，包含"role"和"content"字段。
- ‌role‌:
  - 类型：字符串
  - 描述：指定消息的角色，可以是"system"、"user"或"assistant"。
- ‌content‌:
  - 类型：字符串
  - 描述：消息的实际内容。

可选参数

‌model‌:
- 类型：字符串
- 描述：指定要使用的模型ID。对于DeepSeek-Chat API，推荐使用"deepseek-chat"。
‌frequency_penalty‌:
- 类型：浮点数
- 描述：控制重复内容的惩罚值，范围在-2.0到2.0之间。
‌max_tokens‌:
- 类型：整数
- 描述：限制生成的最大token数。如果不指定，默认最大输出长度为4K。
‌presence_penalty‌:
- 类型：浮点数
- 描述：控制新话题的惩罚值，范围在-2.0到2.0之间。
‌response_format‌:
- 类型：字符串
- 描述：指定输出格式，如JSON。
‌stop‌:
- 类型：字符串或字符串数组
- 描述：停止生成的关键词或关键词列表。当生成的文本出现这些关键词时，API将停止生成更多内容。
‌stream‌:
- 类型：布尔值
- 描述：是否以流式方式发送消息。如果设置为true，API将逐块生成内容，适用于需要实时显示部分结果的场景。
‌temperature‌:
- 类型：浮点数
- 描述：采样温度，控制输出的随机性。值越高，输出越多样化，但也可能更不稳定。
‌top_p‌:
- 类型：浮点数
- 描述：考虑的top概率的token结果。通常与temperature一起使用以调节生成结果。
‌tools‌:
- 类型：数组
- 描述：模型可能调用的工具列表。每个工具都是一个对象，包含"type"和"function"字段。
‌tool_choice‌:
- 类型：字符串
- 描述：控制模型调用工具的行为。
‌logprobs‌:
- 类型：布尔值
- 描述：是否返回输出token的对数概率。
‌top_logprobs‌:
- 类型：整数
- 描述：指定返回输出概率top N的token。

注意事项

当使用流式输出时（即stream参数设置为true），API将逐块生成并返回内容，客户端需要处理这种流式响应。
max_tokens参数用于控制生成内容的长度，如果不指定，默认最大输出长度为4K。
tools参数允许调用外部API或执行特定计算，为模型提供额外的功能。
在实际调用API时，请确保遵循DeepSeek平台的API文档和最佳实践，以获得最佳性能和可靠性。

4. 发送请求

使用编程语言或工具（如 Python 的 requests 库、Postman 等）发送 HTTP 请求。

5. 处理响应

接收并解析 API 返回的响应数据，通常也是 JSON 格式。

错误处理：检查 API 返回的状态码和错误信息。如果调用失败，确保请求参数正确无误，并检查网络连接。
成本控制：DeepSeek API 是按调用次数收费的。合理规划调用频率，避免不必要的调用以节省成本。
日志记录：在开发过程中，可以记录请求和响应日志，方便调试和优化。

6. Java调用DeepSeek API

url配置

调用DeepSeek提供的api服务

   public String deepSeekServerApi(String query) {
        // 设置请求头（根据需要添加）
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.setBearerAuth(DeepSeekAPIKey);
        // 构建请求体
        String requestPayload = String.format("{"+
            "\"model\": \"deepseek-chat\","+
                "\"messages\": [{\"role\": \"user\", \"content\": \"%s\"}," +
                "{\"role\": \"system\", \"content\": \"智能助手\"}],"+
            "\"stream\": false}",query);

        // 将请求体和请求头封装到HttpEntity中
        HttpEntity<String> entity = new HttpEntity<>(requestPayload, headers);

        // 发送POST请求，并接收响应
        // org.springframework.web.client.HttpClientErrorException: 402 Payment Required: "{"error":{"message":"Insufficient Balance","type":"unknown_error","param":null,"code":"invalid_request_error"}}"
        ResponseEntity<String> response = restTemplate.postForEntity(
                deepSeekServerApiUrl,
                entity,
                String.class
        );
        // 返回响应体
        return response.getBody();
    }

可惜报错

402 Payment Required: "{"error":{"message":"Insufficient Balance","type":"unknown_error","param":null,"code":"invalid_request_error"}}"

通常表示您的账户余额不足，无法完成该请求。

调用火山引擎的DeepSeek api服务

签名鉴权方式--火山方舟大模型服务平台-火山引擎

public String deepSeekArkApi(String query) {
        // 设置请求头（根据需要添加）
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.setBearerAuth(DeepSeekArkApiKey);
        // 构建请求体
        String requestPayload = String.format("{"+
                "\"model\": \"deepseek-chat\","+
                "\"messages\": [{\"role\": \"user\", \"content\": \"%s\"}," +
                "{\"role\": \"system\", \"content\": \"智能助手\"}],"+
                "\"stream\": false}",query);

        // 将请求体和请求头封装到HttpEntity中
        HttpEntity<String> entity = new HttpEntity<>(requestPayload, headers);

        // 发送POST请求，并接收响应
        // org.springframework.web.client.HttpClientErrorException: 402 Payment Required: "{"error":{"message":"Insufficient Balance","type":"unknown_error","param":null,"code":"invalid_request_error"}}"
        ResponseEntity<String> response = restTemplate.postForEntity(
                deepSeekArkApiUrl,
                entity,
                String.class
        );
        // 返回响应体
        return response.getBody();
    }

可惜报错

500 Internal Server Error: "{"error":{"code":"InternalServiceError","message":"The service encountered an unexpected internal error. Request id: 021740231281568f4ecf41968ddf3f2b18063be33e838bcb7dbba","param":"","type":"InternalServerError"}}"

调用火山引擎 DeepSeek API 时遇到 HTTP 500（Internal Server Error）属于服务端异常，建议按以下优先级排查：

请求有效性验证

检查 API 端点 URL 是否与官方文档一致（注意区域节点选择）
确认 Authorization 头格式正确，Bearer Token 包含有效 API 密钥
验证请求体 JSON 格式符合规范（建议使用 JSON Lint 工具）

服务状态检查

访问火山引擎官方状态页面（需登录控制台）
查看 API 服务是否存在计划维护或突发故障
关注火山引擎开发者公告渠道获取实时状态更新

请求重试机制

采用指数退避策略进行重试（建议间隔 2 秒、5 秒、10 秒）
确保请求频率未超过 API 速率限制（免费版默认限制为 5 QPS）

技术支持介入

将请求 ID（021740231281568f4ecf41968ddf3f2b18063be33e838bcb7dbba）提交至火山引擎工单系统
通过 API 控制台下载完整的请求日志副本
提供可稳定复现的测试用例供技术团队分析

该错误响应明确标识为服务端内部错误（InternalServerError），建议优先排除客户端参数问题后，通过火山引擎官方支持渠道进行深度追踪。若为偶发性错误，重试机制通常可有效恢复服务。

常见错误处理

错误场景	可能原因	解决方案
401 Unauthorized	API 密钥无效或缺失	检查 Authorization 头是否正确
429 Too Many Requests	API 调用超出速率限制	降低调用频率或升级 API 权限
400 Bad Request	请求参数格式错误	检查 text 是否为空或超长
500 Internal Error	服务器端错误	联系 DeepSeek 支持团队