Skip to main content

Responses API

POST 

/responses

Creates a model response in the OpenAI Responses API format.

The API is stateless: responses and conversations are not stored on the server. For multi-turn conversations, the client needs to send the full conversation history in input on each request. Please refer to the Responses API Guide for details, including the full parameter compatibility tables.

Request​

Body

required

    model stringrequired

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

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

    input string | object[]

    nullable

    The input to the model. Either a plain string (treated as a single user message), or a list of input items.

    Supported input item types are message / function_call / function_call_output / custom_tool_call / custom_tool_call_output / reasoning / web_search_call; other types are ignored. Message roles can be user / assistant / system / developer (developer is treated as system with deepseek-flash and as user with deepseek-v4-pro). With the deepseek-flash model, input_image content parts are supported in user / system / developer message items and in the output of function_call_output / custom_tool_call_output items; images in assistant messages return a 400 error. In user messages, input_file with a file_id references an uploaded file, see File Parsing; file_url is not supported.

    At least one of input and instructions is required.

    With the web tools or safety_check set to high, some input items are not accepted. See the Web Tools guide.

    oneOf

    string

    instructions stringnullable

    A system-level instruction, inserted as the first system message of the model's context.

    reasoning

    object

    nullable

    Configuration of the thinking mode.

    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. If not set, the model's default thinking behavior is used (enabled by default). For compatibility with existing software, minimal is accepted and mapped to low, and medium / xhigh are accepted and mapped to high.

    max_output_tokens integernullable

    An upper bound for the number of tokens that can be generated in the response, including both the visible output tokens and the reasoning tokens.

    stream booleannullable

    Default value: false

    If set to true, the response is streamed as semantic server-sent events. The final event is response.completed / response.incomplete / response.failed (there is no data: [DONE] message). Please refer to the Responses API Guide for the full event list.

    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. Has no effect in thinking mode.

    top_p numbernullable

    Possible values: >= 0 and <= 1

    An alternative to sampling with temperature, called nucleus sampling. 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.

    text

    object

    nullable

    Configuration of the text output.

    format

    object

    The output format. {"type": "text"} (default) for plain text; {"type": "json_object"} for JSON mode; {"type": "json_schema", "name": ..., "schema": ...} for structured output conforming to the given JSON Schema.

    If text is omitted or null, or format is omitted, plain text is used. When a format object is provided, type is required.

    type stringrequired

    Possible values: text, json_object, json_schema

    name string

    The name of the schema. Required when type is json_schema.

    schema object

    The JSON Schema that the output must conform to. Required when type is json_schema.

    tools

    object[]

    nullable

    A list of tools the model may call. Function names must be non-empty, at most 128 characters, match ^[a-zA-Z0-9_-]+$, and be unique across all tools. function tools are supported; web_search is supported with deepseek-v4-pro; other built-in tool types are ignored. Please refer to the Responses API Guide for details.

    A tool the model may call. function defines a function tool — note that in the Responses API format, name / parameters and other function fields are at the top level of the tool object. custom defines a custom tool; only {"type": "custom", "name": "apply_patch"} is supported, and other names return a 400 error. web_search enables server-side web search and is supported with deepseek-v4-pro. deepseek_web_search and deepseek_read_url are the web tools; they cannot be declared together with web_search. See the Web Tools guide.

  • Array [

  • type stringrequired

    Possible values: function, custom, web_search, deepseek_web_search, deepseek_read_url

    The type of the tool: function, custom (only apply_patch), web_search (deepseek-v4-pro only), deepseek_web_search or deepseek_read_url.

    name string

    For function and custom tools. The name of the tool. For function tools, must be non-empty, at most 128 characters, match ^[a-zA-Z0-9_-]+$, and be unique across all tools. For custom tools, must be apply_patch.

    description string

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

    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
  • ]

  • 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 (default) 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", "name": "my_function"} forces the model to call that tool.

    oneOf

    string

    Possible values: none, auto, required

    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.

    user stringnullable

    A custom end-user identifier. 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.

    • It can be used to distinguish user identities on your side to help us with content safety review, for KVCache isolation, and for scheduling isolation. For more details, please refer to Rate Limit & Isolation

    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.

Responses​

OK, returns a response object

Schema

    id stringrequired

    A unique identifier for the response.

    object stringrequired

    Possible values: response

    The object type, which is always response.

    created_at integerrequired

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

    status stringrequired

    Possible values: in_progress, completed, incomplete, failed

    The status of the response.

    error objectnullable

    The error object when the response failed, with code and message fields.

    incomplete_details

    object

    nullable

    The details about why the response is incomplete. The reason field can be max_output_tokens or content_filter.

    reason string

    Possible values: max_output_tokens, content_filter

    model stringrequired

    The model used for the response.

    output

    object[]

    required

    The list of output items generated by the model. In thinking mode, the chain-of-thought is returned as a reasoning item before the message item. Function calls are returned as function_call items.

    An output item generated by the model. message items carry the assistant text, reasoning items carry the chain-of-thought, function_call items represent function calls, custom_tool_call items represent custom tool calls (such as apply_patch), web_search_call items represent server-side web searches (deepseek-v4-pro only), and tool_search_call items represent tool searches. With the web tools, every tool call is a web_search_call item with the extension fields kind, page, signature and error.

  • Array [

  • type string

    Possible values: message, reasoning, function_call, custom_tool_call, web_search_call, tool_search_call

    The type of the output item: message / reasoning / function_call / custom_tool_call / web_search_call / tool_search_call.

    id string

    The unique ID of the output item.

    status string

    Possible values: in_progress, completed, incomplete

    The status of the output item.

    role string

    Possible values: assistant

    For message items. Always assistant.

    content

    object[]

    For message items, a list of output_text content parts. For reasoning items, a list of reasoning_text content parts carrying the chain-of-thought in plain text.

  • Array [

  • type string

    Possible values: output_text, reasoning_text

    text string
  • ]

  • call_id string

    For function_call / custom_tool_call / tool_search_call items. An identifier used when passing the tool output back to the API.

    name string

    For function_call / custom_tool_call items. The name of the function or custom tool to call.

    arguments string

    For function_call items. 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.

    kind Web tools capability (string)

    Possible values: search, deep_search, read_link, image_search, deep_image_search

    DeepSeek extension on blocks produced by the web tools: search for web search, deep_search for deep thinking search, read_link for URL reading, and image_search or deep_image_search (during deep thinking search) for image search. Pass it back unchanged.

    action object

    For web_search_call items. type is search (with queries and sources), open_page (with url) or find_in_page (with url and pattern). With the web tools, each element of sources also carries title, snippet, site_name, site_icon and published_at for display.

    page object

    DeepSeek extension, for web_search_call items that opened or read a page: url, title and published_at. The page text is not returned.

    signature string

    DeepSeek extension, for successful read_link calls. The page, encrypted. Pass it back unchanged so that the page is restored into the context.

    error object

    DeepSeek extension, for failed web_search_call items (status is failed). code is unavailable, url_not_accessible or url_not_allowed.

  • ]

  • title string

    DeepSeek extension. The conversation title, present only when the request enabled title and a title was generated. In streaming responses, read it from response.title in the final event.

    usage

    object

    nullable

    Token and server-tool usage statistics for the response. Null in initial streaming events; read usage from the final response.

    input_tokens integerrequired

    Number of input tokens.

    input_tokens_details

    object

    Breakdown of the input tokens.

    cached_tokens integer

    Number of input tokens that hit the context cache. See Context Caching.

    output_tokens integerrequired

    Number of output tokens.

    output_tokens_details

    object

    Breakdown of the output tokens.

    reasoning_tokens integer

    Number of reasoning (chain-of-thought) tokens generated by the model.

    safety_tokens integer

    Possible values: >= 0

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

    total_tokens integerrequired

    Total number of tokens used in the request (input + output).

    server_tool_use

    object

    Successful server-side web search and page-fetch counts, separate from token usage. Present only when one of the counts is greater than zero; otherwise omitted. All fields are present when this object is returned. In streaming responses, read response.usage from the terminal response.completed, response.incomplete, or response.failed event. These are cumulative counts, not deltas. See Server tool usage.

    tool_search integerrequired

    Possible values: >= 0

    Number of successful web search queries. A search with multiple queries can add more than one.

    tool_fetch integerrequired

    Possible values: >= 0

    Number of successful page fetches performed by open_page or find_in_page. With the web tools, finding text in a page is not counted.

    tool_image_search integer

    Possible values: >= 0

    With the web tools. Number of successful image searches.

Loading...