# Responses API

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](https://api-docs.deepseek.com/guides/responses_api.md) for details, including the full parameter compatibility tables.

## Endpoint

```http
POST /responses
```

operationId: `createResponse`

### Servers

- `https://api.deepseek.com`

## Authentication

### Alternative 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

```yaml
type: http
scheme: bearer
```

## Request body

**required**

### application/json

- Reference: [CreateResponseRequest](#schema-create-response-request) (`#/components/schemas/CreateResponseRequest`)

## Responses

### 200 (No streaming)

OK, returns a `response` object

#### application/json

- Reference: [Response](#schema-response) (`#/components/schemas/Response`)

**Example**

```json
{
  "id": "387b53c1-7ad2-4259-9298-61b139f5bd20",
  "object": "response",
  "created_at": 1793084842,
  "status": "completed",
  "background": false,
  "completed_at": 1793084843,
  "content_filters": null,
  "error": null,
  "frequency_penalty": 0.0,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": 32,
  "max_tool_calls": null,
  "model": "deepseek-flash",
  "moderation": null,
  "output": [
    {
      "type": "message",
      "id": "4e706f35-6ea2-468a-bd19-a9c1adc54726",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Hello! 👋 How can I help you today?"
        }
      ],
      "phase": "final_answer",
      "role": "assistant"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0.0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "prompt_cache_retention": null,
  "reasoning": {
    "effort": "none",
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "default",
  "store": false,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": null
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 7,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 11,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 18
  },
  "user": null,
  "metadata": {}
}
```

### 200 (Streaming)

OK, returns a streamed sequence of semantic server-sent events. Each event has an `event` field for the event type and an incrementing `sequence_number`. The final event is `response.completed` / `response.incomplete` / `response.failed` (there is no `data: [DONE]` message). Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md#streaming) for the full event list.

#### text/event-stream

- `type`: `array`

- **Array items**

  - `type`: `object`

**Example**

```
event: response.created
data: {"type":"response.created","response":{"id":"19460ef2-58da-46c5-9510-9e7b04c47e4a","object":"response","created_at":1793084908,"status":"in_progress","background":false,"completed_at":null,"content_filters":null,"error":null,"frequency_penalty":0.0,"incomplete_details":null,"instructions":null,"max_output_tokens":32,"max_tool_calls":null,"model":"deepseek-flash","moderation":null,"output":[],"parallel_tool_calls":true,"presence_penalty":0.0,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":{"effort":"none","summary":null},"safety_identifier":null,"service_tier":"default","store":false,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":null},"tool_choice":"auto","tools":[],"top_logprobs":0,"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}},"sequence_number":0}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"19460ef2-58da-46c5-9510-9e7b04c47e4a","object":"response","created_at":1793084908,"status":"in_progress","background":false,"completed_at":null,"content_filters":null,"error":null,"frequency_penalty":0.0,"incomplete_details":null,"instructions":null,"max_output_tokens":32,"max_tool_calls":null,"model":"deepseek-flash","moderation":null,"output":[],"parallel_tool_calls":true,"presence_penalty":0.0,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":{"effort":"none","summary":null},"safety_identifier":null,"service_tier":"default","store":false,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":null},"tool_choice":"auto","tools":[],"top_logprobs":0,"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}},"sequence_number":1}

event: response.output_item.added
data: {"type":"response.output_item.added","item":{"type":"message","id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","status":"in_progress","content":[],"phase":"final_answer","role":"assistant"},"output_index":0,"sequence_number":2}

event: response.content_part.added
data: {"type":"response.content_part.added","content_index":0,"item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","output_index":0,"part":{"type":"output_text","annotations":[],"logprobs":[],"text":""},"sequence_number":3}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":"Hello","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":4}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":"!","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":5}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" 👋","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":6}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" How","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":7}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" can","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":8}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" I","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":9}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" help","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":10}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" you","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":11}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":" today","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":12}

event: response.output_text.delta
data: {"type":"response.output_text.delta","content_index":0,"delta":"?","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":13}

event: response.output_text.done
data: {"type":"response.output_text.done","content_index":0,"item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":14,"text":"Hello! 👋 How can I help you today?"}

event: response.content_part.done
data: {"type":"response.content_part.done","content_index":0,"item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","output_index":0,"part":{"type":"output_text","annotations":[],"logprobs":[],"text":"Hello! 👋 How can I help you today?"},"sequence_number":15}

event: response.output_item.done
data: {"type":"response.output_item.done","item":{"type":"message","id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","status":"completed","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"Hello! 👋 How can I help you today?"}],"phase":"final_answer","role":"assistant"},"output_index":0,"sequence_number":16}

event: response.completed
data: {"type":"response.completed","response":{"id":"19460ef2-58da-46c5-9510-9e7b04c47e4a","object":"response","created_at":1793084908,"status":"completed","background":false,"completed_at":1793084909,"content_filters":null,"error":null,"frequency_penalty":0.0,"incomplete_details":null,"instructions":null,"max_output_tokens":32,"max_tool_calls":null,"model":"deepseek-flash","moderation":null,"output":[{"type":"message","id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","status":"completed","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"Hello! 👋 How can I help you today?"}],"phase":"final_answer","role":"assistant"}],"parallel_tool_calls":true,"presence_penalty":0.0,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":{"effort":"none","summary":null},"safety_identifier":null,"service_tier":"default","store":false,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":null},"tool_choice":"auto","tools":[],"top_logprobs":0,"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":7,"input_tokens_details":{"cached_tokens":0},"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":18},"user":null,"metadata":{}},"sequence_number":17}
```

## Code samples

### curl

```bash
# Set DEEPSEEK_API_KEY to your API key before running this example.
curl --silent --show-error --max-time 60 "https://api.deepseek.com/responses" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "deepseek-flash",
  "input": "Say hello.",
  "max_output_tokens": 32,
  "reasoning": {
    "effort": "none"
  },
  "stream": false
}'
```

### Python — OpenAI SDK

```python
# Set DEEPSEEK_API_KEY to your API key before running this example.
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    timeout=60.0,
)

response = client.responses.create(
    model="deepseek-flash",
    input="Say hello.",
    max_output_tokens=32,
    reasoning={"effort": "none"},
    stream=False,
)
print(response.model_dump_json(indent=2))
```

## Referenced schemas

### schema-create-response-request

**CreateResponseRequest** — `#/components/schemas/CreateResponseRequest`

- `type`: `object`

- `required`: `["model"]`

- **Properties**

  - **`model`** (required)

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

    - `type`: `string`

    - `enum`: `["deepseek-flash","deepseek-v4-pro"]`

    **Example**

    ```json
    "deepseek-flash"
    ```

  - **`input`** (optional)

    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](https://api-docs.deepseek.com/guides/document_parsing.md); `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](https://api-docs.deepseek.com/guides/web_tools.md#responses-api).

    - `nullable`: `true`

    - **oneOf**

      - oneOf 1

        - title: `Text input`

        - `type`: `string`

      - oneOf 2

        - title: `Input item list`

        - `type`: `array`

        - **Array items**

          - Reference: [ResponseInputItem](#schema-response-input-item) (`#/components/schemas/ResponseInputItem`)

  - **`instructions`** (optional)

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

    - `type`: `string`

    - `nullable`: `true`

  - **`reasoning`** (optional)

    Configuration of the thinking mode.

    - `type`: `object`

    - `nullable`: `true`

    - **Properties**

      - **`effort`** (optional)

        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`.

        - `type`: `string`

        - `enum`: `["none","low","high","max"]`

  - **`max_output_tokens`** (optional)

    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.

    - `type`: `integer`

    - `nullable`: `true`

    **Example**

    ```json
    4096
    ```

  - **`stream`** (optional)

    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](https://api-docs.deepseek.com/guides/responses_api.md#streaming) for the full event list.

    - `type`: `boolean`

    - `nullable`: `true`

    - `default`: `false`

  - **`temperature`** (optional)

    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.

    - `type`: `number`

    - `minimum`: `0`

    - `maximum`: `2`

    - `default`: `1`

    - `nullable`: `true`

    **Example**

    ```json
    1
    ```

  - **`top_p`** (optional)

    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.

    - `type`: `number`

    - `minimum`: `0`

    - `maximum`: `1`

    - `nullable`: `true`

    **Example**

    ```json
    1
    ```

  - **`text`** (optional)

    Configuration of the text output.

    - `type`: `object`

    - `nullable`: `true`

    - **Properties**

      - **`format`** (optional)

        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`: `object`

        - `required`: `["type"]`

        - **Properties**

          - **`type`** (required)

            - `type`: `string`

            - `enum`: `["text","json_object","json_schema"]`

          - **`name`** (optional)

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

            - `type`: `string`

          - **`schema`** (optional)

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

            - `type`: `object`

  - **`tools`** (optional)

    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](https://api-docs.deepseek.com/guides/responses_api.md) for details.

    - `type`: `array`

    - `nullable`: `true`

    - **Array items**

      - Reference: [ResponseTool](#schema-response-tool) (`#/components/schemas/ResponseTool`)

    **Example**

    ```json
    null
    ```

  - **`tool_choice`** (optional)

    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.

    - `nullable`: `true`

    - **oneOf**

      - oneOf 1

        - title: `Tool choice mode`

        - `type`: `string`

        - `enum`: `["none","auto","required"]`

      - oneOf 2

        - title: `Named tool choice`

        Forces the model to call the specified tool. `name` is required when `type` is `function`.

        - `type`: `object`

        - `required`: `["type"]`

        - **Properties**

          - **`type`** (required)

            - `type`: `string`

            - `enum`: `["function"]`

          - **`name`** (optional)

            The name of the function to call. Required when `type` is `function`.

            - `type`: `string`

  - **`top_logprobs`** (optional)

    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.

    - `type`: `integer`

    - `minimum`: `0`

    - `maximum`: `20`

    - `nullable`: `true`

    - `default`: `null`

    **Example**

    ```json
    null
    ```

  - **`user`** (optional)

    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](https://api-docs.deepseek.com/quick_start/rate_limit.md)

    * `type`: `string`

    * `nullable`: `true`

  - **`safety_check`** (optional)

    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](https://api-docs.deepseek.com/guides/safety.md).

    - `type`: `object`

    - `nullable`: `true`

    - `required`: `["level"]`

    - **Properties**

      - **`level`** (required)

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

        - `type`: `string`

        - `enum`: `["low","high"]`

  - **`title`** (optional)

    DeepSeek extension. Set `{"enabled": true}` to have the response carry a short title for the conversation. See the [Conversation Title Guide](https://api-docs.deepseek.com/guides/conversation_title.md).

    - `type`: `object`

    - `nullable`: `true`

    - `required`: `["enabled"]`

    - **Properties**

      - **`enabled`** (required)

        Whether to return a conversation title.

        - `type`: `boolean`

    - **additionalProperties**

      - Schema: `false`

### schema-response

**Response** — `#/components/schemas/Response`

A model response in the OpenAI Responses API format.

- `type`: `object`

- `required`: `["id","object","created_at","status","model","output"]`

- **Properties**

  - **`id`** (required)

    A unique identifier for the response.

    - `type`: `string`

  - **`object`** (required)

    The object type, which is always `response`.

    - `type`: `string`

    - `enum`: `["response"]`

  - **`created_at`** (required)

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

    - `type`: `integer`

  - **`status`** (required)

    The status of the response.

    - `type`: `string`

    - `enum`: `["in_progress","completed","incomplete","failed"]`

  - **`error`** (optional)

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

    - `type`: `object`

    - `nullable`: `true`

  - **`incomplete_details`** (optional)

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

    - `type`: `object`

    - `nullable`: `true`

    - **Properties**

      - **`reason`** (optional)

        - `type`: `string`

        - `enum`: `["max_output_tokens","content_filter"]`

  - **`model`** (required)

    The model used for the response.

    - `type`: `string`

  - **`output`** (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.

    - `type`: `array`

    - **Array items**

      - Reference: [ResponseOutputItem](#schema-response-output-item) (`#/components/schemas/ResponseOutputItem`)

  - **`title`** (optional)

    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.

    - `type`: `string`

  - **`usage`** (optional)

    - Reference: [ResponseUsage](#schema-response-usage) (`#/components/schemas/ResponseUsage`)

### schema-response-input-item

**ResponseInputItem** — `#/components/schemas/ResponseInputItem`

An input item. Supported types are `message` / `function_call` / `function_call_output` / `custom_tool_call` / `custom_tool_call_output` / `reasoning` / `web_search_call`; other types are ignored. `reasoning` and `function_call` items are automatically merged into the adjacent assistant message by the server. A `web_search_call` item returned by a previous response can be passed back to restore its search results into the context. Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md#multi-turn-conversation) for the pass-back rules in multi-turn conversations.

- `type`: `object`

- **Properties**

  - **`type`** (optional)

    The type of the input item. For `message` items, this field can be omitted if `role` is present. `custom_tool_call` / `custom_tool_call_output` items are used together with the `apply_patch` custom tool. `web_search_call` items restore the search results of a previous server-side search.

    - `type`: `string`

    - `enum`: `["message","function_call","function_call_output","custom_tool_call","custom_tool_call_output","reasoning","web_search_call"]`

  - **`role`** (optional)

    For `message` items. The role of the message author. `developer` is treated as `system` with `deepseek-flash` and as `user` with `deepseek-v4-pro`.

    - `type`: `string`

    - `enum`: `["user","assistant","system","developer"]`

  - **`content`** (optional)

    For `message` items, the message content, either a plain string or a list of `input_text` / `output_text` / `input_image` content parts. For `reasoning` items, a list of `reasoning_text` content parts.

    - **oneOf**

      - oneOf 1

        - title: `Text content`

        - `type`: `string`

      - oneOf 2

        - title: `Array of content parts`

        - `type`: `array`

        - **Array items**

          - Reference: [ResponseInputContentPart](#schema-response-input-content-part) (`#/components/schemas/ResponseInputContentPart`)

  - **`call_id`** (optional)

    For `function_call` / `function_call_output` items. The ID pairing a function call with its output. Must be non-empty and unique, and every `function_call` must have a matching `function_call_output`.

    - `type`: `string`

  - **`name`** (optional)

    For `function_call` items. The name of the function to call.

    - `type`: `string`

  - **`arguments`** (optional)

    For `function_call` items. The arguments to call the function with, in JSON format.

    - `type`: `string`

  - **`output`** (optional)

    For `function_call_output` / `custom_tool_call_output` items. The output of the tool call, either a plain string or a list of `input_text` / `input_image` content parts.

    - **oneOf**

      - oneOf 1

        - title: `Text output`

        - `type`: `string`

      - oneOf 2

        - title: `Array of content parts`

        - `type`: `array`

        - **Array items**

          - Reference: [ResponseInputContentPart](#schema-response-input-content-part) (`#/components/schemas/ResponseInputContentPart`)

### schema-response-tool

**ResponseTool** — `#/components/schemas/ResponseTool`

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](https://api-docs.deepseek.com/guides/web_tools.md#responses-api).

- `type`: `object`

- `required`: `["type"]`

- **Properties**

  - **`type`** (required)

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

    - `type`: `string`

    - `enum`: `["function","custom","web_search","deepseek_web_search","deepseek_read_url"]`

  - **`name`** (optional)

    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`.

    - `type`: `string`

  - **`description`** (optional)

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

    - `type`: `string`

  - **`parameters`** (optional)

    - Reference: [FunctionParameters](#schema-function-parameters) (`#/components/schemas/FunctionParameters`)

### schema-response-output-item

**ResponseOutputItem** — `#/components/schemas/ResponseOutputItem`

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`.

- `type`: `object`

- **Properties**

  - **`type`** (optional)

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

    - `type`: `string`

    - `enum`: `["message","reasoning","function_call","custom_tool_call","web_search_call","tool_search_call"]`

  - **`id`** (optional)

    The unique ID of the output item.

    - `type`: `string`

  - **`status`** (optional)

    The status of the output item.

    - `type`: `string`

    - `enum`: `["in_progress","completed","incomplete"]`

  - **`role`** (optional)

    For `message` items. Always `assistant`.

    - `type`: `string`

    - `enum`: `["assistant"]`

  - **`content`** (optional)

    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.

    - `type`: `array`

    - **Array items**

      - `type`: `object`

      - **Properties**

        - **`type`** (optional)

          - `type`: `string`

          - `enum`: `["output_text","reasoning_text"]`

        - **`text`** (optional)

          - `type`: `string`

  - **`call_id`** (optional)

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

    - `type`: `string`

  - **`name`** (optional)

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

    - `type`: `string`

  - **`arguments`** (optional)

    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.

    - `type`: `string`

  - **`kind`** (optional)

    - Reference: [AnthropicDeepSeekWebToolsKind](#schema-anthropic-deep-seek-web-tools-kind) (`#/components/schemas/AnthropicDeepSeekWebToolsKind`)

  - **`action`** (optional)

    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.

    - `type`: `object`

  - **`page`** (optional)

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

    - `type`: `object`

  - **`signature`** (optional)

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

    - `type`: `string`

  - **`error`** (optional)

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

    - `type`: `object`

### schema-response-usage

**ResponseUsage** — `#/components/schemas/ResponseUsage`

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

- `type`: `object`

- `nullable`: `true`

- `required`: `["input_tokens","output_tokens","total_tokens"]`

- **Properties**

  - **`input_tokens`** (required)

    Number of input tokens.

    - `type`: `integer`

  - **`input_tokens_details`** (optional)

    Breakdown of the input tokens.

    - `type`: `object`

    - **Properties**

      - **`cached_tokens`** (optional)

        Number of input tokens that hit the context cache. See [Context Caching](https://api-docs.deepseek.com/guides/kv_cache.md).

        - `type`: `integer`

  - **`output_tokens`** (required)

    Number of output tokens.

    - `type`: `integer`

  - **`output_tokens_details`** (optional)

    Breakdown of the output tokens.

    - `type`: `object`

    - **Properties**

      - **`reasoning_tokens`** (optional)

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

        - `type`: `integer`

      - **`safety_tokens`** (optional)

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

        - `type`: `integer`

        - `minimum`: `0`

  - **`total_tokens`** (required)

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

    - `type`: `integer`

  - **`server_tool_use`** (optional)

    - title: `Server tool usage`

    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](https://api-docs.deepseek.com/guides/responses_api.md#server-tool-usage).

    - `type`: `object`

    - `required`: `["tool_search","tool_fetch"]`

    - **Properties**

      - **`tool_search`** (required)

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

        - `type`: `integer`

        - `minimum`: `0`

      - **`tool_fetch`** (required)

        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.

        - `type`: `integer`

        - `minimum`: `0`

      - **`tool_image_search`** (optional)

        With the web tools. Number of successful image searches.

        - `type`: `integer`

        - `minimum`: `0`

    **Example**

    ```json
    {
      "tool_search": 1,
      "tool_fetch": 0
    }
    ```

### schema-response-input-content-part

**ResponseInputContentPart** — `#/components/schemas/ResponseInputContentPart`

- **oneOf**

  - oneOf 1

    - Reference: [ResponseInputTextContentPart](#schema-response-input-text-content-part) (`#/components/schemas/ResponseInputTextContentPart`)

  - oneOf 2

    - Reference: [ResponseInputImageContentPart](#schema-response-input-image-content-part) (`#/components/schemas/ResponseInputImageContentPart`)

  - oneOf 3

    - Reference: [ResponseInputFileContentPart](#schema-response-input-file-content-part) (`#/components/schemas/ResponseInputFileContentPart`)

  - oneOf 4

    - Reference: [ResponseInputReasoningTextContentPart](#schema-response-input-reasoning-text-content-part) (`#/components/schemas/ResponseInputReasoningTextContentPart`)

### schema-function-parameters

**FunctionParameters** — `#/components/schemas/FunctionParameters`

The parameters the functions accepts, described as a JSON Schema object. See the [Tool Calls Guide](https://api-docs.deepseek.com/guides/tool_calls.md) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.

Omitting `parameters` defines a function with an empty parameter list.

- `type`: `object`

- **additionalProperties**

  - Schema: `true`

### schema-anthropic-deep-seek-web-tools-kind

**AnthropicDeepSeekWebToolsKind** — `#/components/schemas/AnthropicDeepSeekWebToolsKind`

- title: `Web tools capability`

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.

- `type`: `string`

- `enum`: `["search","deep_search","read_link","image_search","deep_image_search"]`

### schema-response-input-text-content-part

**ResponseInputTextContentPart** — `#/components/schemas/ResponseInputTextContentPart`

- title: `Text content part`

- `type`: `object`

- `required`: `["type","text"]`

- **Properties**

  - **`type`** (required)

    The type of the content part.

    - `type`: `string`

    - `enum`: `["input_text","output_text"]`

  - **`text`** (required)

    The text content.

    - `type`: `string`

### schema-response-input-image-content-part

**ResponseInputImageContentPart** — `#/components/schemas/ResponseInputImageContentPart`

- title: `Image content part`

An image content part. Processed as a real image. Allowed 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.

- `type`: `object`

- `required`: `["type"]`

- **Properties**

  - **`type`** (required)

    The type of the content part, in this case `input_image`.

    - `type`: `string`

    - `enum`: `["input_image"]`

  - **`image_url`** (optional)

    The image source, either an `http(s)` URL of the image (max 8192 characters) or a base64-encoded data URL (`data:image/jpeg;base64,...`). Supported formats: JPEG, PNG, GIF, and WebP. Mutually exclusive with `file_id`: passing neither returns a `400` error ("input\_image must have image\_url or file\_id"); passing both returns a `400` error ("input\_image cannot have both image\_url and file\_id").

    - `type`: `string`

  - **`detail`** (optional)

    Controls how the image is processed. `low` downsamples the image to 512x512 (faster, cheaper). `high`, `original`, and `auto` keep the original image. Ignored when `file_id` is set.

    - `type`: `string`

    - `enum`: `["low","high","original","auto"]`

  - **`file_id`** (optional)

    The ID of an image file uploaded via the [Files API](https://api-docs.deepseek.com/guides/files_api.md), of the form `file-api-...`. Mutually exclusive with `image_url`; `detail` is ignored when `file_id` is set.

    - `type`: `string`

### schema-response-input-file-content-part

**ResponseInputFileContentPart** — `#/components/schemas/ResponseInputFileContentPart`

- title: `File content part`

References a file uploaded via the Files API. Allowed in `user` message items. See the [File Parsing guide](https://api-docs.deepseek.com/guides/document_parsing.md#document-qa).

- `type`: `object`

- `required`: `["type","file_id"]`

- **Properties**

  - **`type`** (required)

    The type of the content part, in this case `input_file`.

    - `type`: `string`

    - `enum`: `["input_file"]`

  - **`file_id`** (required)

    The ID of the uploaded file, of the form `file-api-...`.

    - `type`: `string`

### schema-response-input-reasoning-text-content-part

**ResponseInputReasoningTextContentPart** — `#/components/schemas/ResponseInputReasoningTextContentPart`

- title: `Reasoning text content part`

- `type`: `object`

- `required`: `["type","text"]`

- **Properties**

  - **`type`** (required)

    The type of the content part, in this case `reasoning_text`.

    - `type`: `string`

    - `enum`: `["reasoning_text"]`

  - **`text`** (required)

    The chain-of-thought text content.

    - `type`: `string`
