The DeepSeek API is a powerful tool for developers looking to integrate advanced natural language processing into their applications. At its core lies the "Create Chat Completion" endpoint, which allows you to generate model responses for given chat conversations. This article will provide a detailed walkthrough of how to use this endpoint effectively, covering everything from setting up your request to understanding the nuances of the response.
The POST /chat/completions endpoint is the cornerstone for creating interactive and dynamic conversational experiences with the DeepSeek API. It enables you to send a structured dialogue to the model and receive a generated response, making it perfect for chatbots, virtual assistants, and content generation tools.
To effectively use the Create Chat Completion endpoint, it's important to understand the key parameters you can adjust in your request. Here's a breakdown:
messages (required): This array contains the history of the conversation, and each message is itself an object with role and content.
system, user, and assistant.
system: Used for setting the behavior and context for the model. For example, "role": "system", "content": "You are a helpful assistant" sets the tone for the entire conversation.user: Represents the end-user's input. For example,"role": "user", "content": "What is the capital of France?" is a typical question from a user.assistant: Represents a prior response from the model. Including this helps to maintain context across multiple turns.model (required): Specifies which DeepSeek model to use. Options include deepseek-chat which is optimized for converstaional tasks and deepseek-reasoner which is designed for complex reasoning tasks.
temperature (nullable): Controls the randomness of the model's output.
0 produce more predictable, focused responses.2 introduce more randomness and creativity.top_p, not both.top_p (nullable): Also known as nucleus sampling, top_p lets the model consider the results of the tokens with top_p probably mass.
0.1 means only the tokens comprising the top 10% probablility mass are consideredmax_tokens (nullable): Sets the maximum number of tokens generated in the chat completion.
stop (nullable): Allows you to specify up to 16 sequences where the API will stop generating furthermore tokens.
stream (nullable): Enables real-time streaming of responses.
true, the API sends data in chunks via server-sent events (SSE).tools (nullable): An array of tools or function calls that allows you to extend the capabilities of the deepseek-chat model.
tool_choice (nullable): Controls whether or not the deep-seek chat model can use the "tools" you provided.
response_format (nullable): Specifies the format of the model output. Setting {"type": "json_object"} guarantees a valid JSON response.
Here's an example of a request body showcasing several parameters:
{
"model": "deepseek-chat",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant that provides information about historical events."
},
{
"role": "user",
"content": "Tell me about the French Revolution."
}
],
"temperature": 0.7,
"max_tokens": 200
}
This request instructs the deepseek-chat model to respond to the user's query about the French Revolution, with a moderate level of randomness (temperature 0.7) and a limit of 200 tokens.
The API returns a JSON response containing various fields. Here's what you need to know:
assistant, as this is the model's reply.stop, length, content_filter, tool_calls, or insufficient_system_resource).prompt_tokens, completion_tokens, total_tokens).For applications requiring real-time interactions, the stream parameter is invaluable. By setting "stream": true, the API sends responses in chunks, allowing you to display content as it's generated.
Each chunk contains a delta object with the incremental content. The final chunk includes finish_reason to signal the end of the stream.
The tools parameter allows you to extend the deepseek-chat model. You can use function calling by:
tools parameter.Refer to the Function Calling Guide and JSON Schema reference for complete information on how to use this feature.
The DeepSeek API’s Create Chat Completion endpoint offers a flexible and powerful way to integrate conversational AI into your projects. By carefully crafting your requests and understanding the nuances of the responses, you can create engaging and intelligent applications. Make sure you also understand the Token & Token Usage and Rate Limit policies to optimize your usage and avoid potential issues.
