Skip to main content

Chat Completions API

POST 

/chat/completions

Creates a model response for the given chat conversation.

Request​

Body

required

    messages

    object[]

    required

    Minimum items: 1

    A list of messages comprising the conversation so far.

  • Array [

  • oneOf

    content stringrequired

    The contents of the system message.

    role stringrequired

    Possible values: system

    The role of the messages author, in this case system.

    name string

    An optional name for the participant. Provides the model information to differentiate between participants of the same role.

  • ]

  • model stringrequired

    Possible values: deepseek-flash, deepseek-v4-pro

    ID of the model to use. Use deepseek-flash or deepseek-v4-pro.

    thinking

    object

    nullable

    Controls the switch between thinking and non-thinking mode. When thinking is omitted or null, the mode follows reasoning_effort; if reasoning_effort is also omitted, thinking is enabled. When this object is provided, type is required and takes precedence over reasoning_effort for selecting the mode.

    type stringrequired

    Possible values: enabled, disabled

    If set to enabled, then use thinking mode. If set to disabled, then use non-thinking model.

    reasoning_effort string

    Possible values: none, low, high, max

    Controls the thinking mode toggle and the thinking effort. none disables thinking mode; low / high / max enable thinking mode. The default effort is high. For compatibility with existing software, minimal is accepted and mapped to low, and medium / xhigh are accepted and mapped to high.

    max_tokens integernullable

    The maximum number of tokens that can be generated in the chat completion.

    The total length of input tokens and generated tokens is limited by the model's context length.

    The value must be between 1 and 384K (393216). When not set, the default is 8K in non-thinking mode, 64K in thinking mode (128K with reasoning_effort set to max). Please refer to the Models & Pricing page for details.

    response_format

    object

    nullable

    An object specifying the format that the model must output. If omitted or null, plain text is used. When this object is provided, type is required. Setting to { "type": "json_object" } enables JSON Output, which guarantees the message the model generates is valid JSON.

    Important: When using JSON Output, you must also instruct the model to produce JSON yourself via a system or user message. If the model's output cannot be recognized as JSON, the API replaces the non-JSON content with spaces (U+0020). As a result, the message content may contain only spaces (appearing empty), even when finish_reason is stop. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.

    type stringrequired

    Possible values: text, json_object

    Must be one of text or json_object.

    stop string | string[]

    nullable

    Default value: null

    Up to 16 sequences where the API will stop generating further tokens. Each sequence must be a non-empty string of at most 512 bytes (UTF-8 encoded).

    oneOf

    string

    stream booleannullable

    Default value: false

    If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events (SSE) as they become available, with the stream terminated by a data: [DONE] message.

    stream_options

    object

    nullable

    Default value: null

    Options for streaming response. Must be set together with stream: true; if stream is not set to true, the API returns a 400 error.

    include_usage boolean

    If set to true, all chunks in the stream will include a usage field, whose value is null on every chunk except the last one. If omitted or set to false, the usage field is absent from all chunks except the last one.

    Either way, the last chunk before the data: [DONE] message carries the token usage statistics for the entire request in its usage field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose choices array always contains exactly one element that carries no new content and a non-null finish_reason.

    temperature numbernullable

    Possible values: >= 0 and <= 2

    Default value: 1

    What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

    We generally recommend altering this or top_p but not both. Has no effect in thinking mode.

    top_p numbernullable

    Possible values: > 0 and <= 1

    An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

    The value must be greater than 0 and at most 1. We generally recommend altering this or temperature but not both. The effective value depends on the model and mode:

    • deepseek-flash: In thinking mode, the default is 1.0 and values below 0.95 are treated as 0.95. In non-thinking mode, it is fixed at 1.0 and the value you pass is ignored.
    • deepseek-v4-pro: In thinking mode, it is fixed at 0.95 when tool calling is enabled, or 1.0 otherwise; the value you pass is ignored. Setting tool_choice to none disables tool calling even when tools is provided. In non-thinking mode, the value you pass is used, with a default of 1.0.

    tools

    object[]

    nullable

    A list of tools the model may call: functions, and the web tools deepseek_web_search and deepseek_read_url (see the Web Tools Guide). Use functions to provide a list of functions the model may generate JSON inputs for. Tool names must be unique.

  • Array [

  • oneOf

    type stringrequired

    Possible values: function

    The type of the tool, in this case function.

    function

    object

    required

    description string

    A description of what the function does, used by the model to choose when and how to call the function.

    name stringrequired

    The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

    parameters

    object

    The parameters the functions accepts, described as a JSON Schema object. See the Tool Calls Guide for examples, and the JSON Schema reference for documentation about the format.

    Omitting parameters defines a function with an empty parameter list.

    property name* anynullable
    strict boolean

    Default value: false

    If set to true, the API will use strict-mode for the tool calls to ensure the output always complies with the function's JSON schema. This is a Beta feature, for more details please refer to Tool Calls Guide

  • ]

  • tool_choice string | object

    nullable

    Controls which (if any) tool is called by the model.

    none means the model will not call any tool and instead generates a message.

    auto means the model can pick between generating a message or calling one or more tools.

    required means the model must call one or more tools.

    Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.

    none is the default when no tools are present. auto is the default if tools are present.

    required and named tool choices are not supported in thinking mode; the API returns a 400 error. Disable thinking mode first to use them. With the web tools declared, required is treated as auto.

    oneOf

    string

    Possible values: none, auto, required

    safety_check

    object

    nullable

    DeepSeek extension. Set level to high to turn on basic risk control, which reviews the model input and output. See the Model Content Safety Guide.

    level stringrequired

    Possible values: low, high

    high: basic risk control. low: the default checks, the same as omitting safety_check.

    title

    object

    nullable

    DeepSeek extension. Set {"enabled": true} to have the response carry a short title for the conversation. See the Conversation Title Guide.

    enabled booleanrequired

    Whether to return a conversation title.

    logprobs booleannullable

    Default value: false

    Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.

    top_logprobs integernullable

    Possible values: >= 0 and <= 20

    Default value: null

    An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.

    user_id nullable

    A custom user_id. We recommend using only ASCII letters, digits, underscores (_), and hyphens (-). The UTF-8 encoded value must not exceed 512 bytes. Do not include user privacy information in the user_id.

    • user_id can be used to distinguish user identities on your side to help us with content safety review.
    • user_id can be used for KVCache isolation for privacy management.
    • user_id can be used for scheduling isolation of users on your business side.
    • For more details on the user_id parameter, please refer to Rate Limit & Isolation
    frequency_penalty nullabledeprecated

    This parameter is no longer supported. It will not take effect if you pass it to the API.

    presence_penalty nullabledeprecated

    This parameter is no longer supported. It will not take effect if you pass it to the API.

Responses​

OK, returns a chat completion object

Schema

    id stringrequired

    A unique identifier for the chat completion.

    choices

    object[]

    required

    A list of chat completion choices.

  • Array [

  • finish_reason stringrequired

    Possible values: stop, length, content_filter, tool_calls, insufficient_system_resource, aborted

    The reason the model stopped generating tokens. This will be stop if the model hit a natural stop point or a provided stop sequence, length if the maximum number of tokens specified in the request was reached, content_filter if content was omitted due to a flag from our content filters, tool_calls if the model called a tool, insufficient_system_resource if the request is interrupted due to insufficient resource of the inference system, or aborted if the generation was interrupted.

    index integerrequired

    The index of the choice in the list of choices.

    message

    object

    required

    A chat completion message generated by the model.

    content stringnullablerequired

    The contents of the message.

    reasoning_content stringnullable

    For thinking mode only. The reasoning contents of the assistant message, before the final answer.

    tool_calls

    object[]

    The tool calls generated by the model.

  • Array [

  • id stringrequired

    The ID of the tool call.

    type stringrequired

    Possible values: function

    The type of the tool. Currently, only function is supported.

    function

    object

    required

    The function that the model called.

    name stringrequired

    The name of the function to call.

    arguments stringrequired

    The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

  • ]

  • role stringrequired

    Possible values: assistant

    The role of the author of this message.

    annotations object[]

    With the web tools. The citations in content. See Web Tools - Citations.

    server_tool_calls object[]

    DeepSeek extension. With the web tools. The server-side tool calls of this response, one entry per step; pass it back unchanged in the next request. See the Web Tools Guide.

    title string

    DeepSeek extension. The conversation title, returned when title.enabled is true. See the Conversation Title Guide.

    refusal string

    Names the blocked images when images in the request fail the model content safety review. See the Model Content Safety Guide.

    logprobs

    object

    nullable

    required

    Log probability information for the choice.

    content

    object[]

    nullable

    required

    A list of message content tokens with log probability information.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

    top_logprobs

    object[]

    required

    List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

  • ]

  • ]

  • reasoning_content

    object[]

    nullable

    A list of message content tokens with log probability information.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

    top_logprobs

    object[]

    required

    List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

  • ]

  • ]

  • ]

  • created integerrequired

    The Unix timestamp (in seconds) of when the chat completion was created.

    model stringrequired

    The model used for the chat completion.

    system_fingerprint stringrequired

    This fingerprint represents the backend configuration that the model runs with.

    object stringrequired

    Possible values: chat.completion

    The object type, which is always chat.completion.

    usage

    object

    Usage statistics for the completion request.

    completion_tokens integerrequired

    Number of tokens in the generated completion.

    prompt_tokens integerrequired

    Number of tokens in the prompt. It equals prompt_cache_hit_tokens + prompt_cache_miss_tokens.

    prompt_tokens_details

    object

    required

    Breakdown of tokens used in the prompt.

    cached_tokens integer

    Number of tokens in the prompt that hit the context cache. Same as prompt_cache_hit_tokens.

    prompt_cache_hit_tokens integerrequired

    Number of tokens in the prompt that hits the context cache.

    prompt_cache_miss_tokens integerrequired

    Number of tokens in the prompt that misses the context cache.

    total_tokens integerrequired

    Total number of tokens used in the request (prompt + completion).

    completion_tokens_details

    object

    Breakdown of tokens used in a completion.

    reasoning_tokens integer

    Tokens generated by the model for reasoning.

    safety_tokens integer

    Possible values: >= 0

    DeepSeek extension. Tokens of the safety review, already included in completion_tokens. Present only when safety_check is high.

    server_tool_use

    object

    With the web tools. The numbers of searches and fetches; omitted when all counts are zero. See the Web Tools Guide.

    tool_search integer

    Possible values: >= 0

    Number of searches, excluding image searches.

    tool_fetch integer

    Possible values: >= 0

    Number of page fetches.

    tool_image_search integer

    Possible values: >= 0

    Number of image searches.

Loading...