> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek 웹 검색 API 레퍼런스

> DeepSeek Search API 레퍼런스 및 플레이그라운드: /v1/tools/search 파라미터, 검색 연산자, 응답 구조 및 오류 코드.

> [!NOTE]
>
> 오른쪽 Playground에서 사용해 보세요: **Authorization**에 `Bearer sk-your-api-key`(`default` 또는 `svip` 그룹의 키)를 입력합니다.
> 기본 예제가 미리 입력되어 있으므로 전송을 클릭하여 결과를 확인할 수 있습니다. 호출이 성공할 때마다 1회 과금됩니다.
> `localization`은 **사용자의 IP 주소**(예: `8.8.8.8`)를 사용하며, `en-US`와 같은 로케일 코드는 400을 반환합니다.

> [!TIP]
>
> 가격 정보, 테스트 데이터 및 필수 안내 사항은 [개요](/ko/api-capabilities/deepseek-search-fetch/overview)에서 확인할 수 있습니다.

## 파라미터 참조

| 파라미터 | 타입 | 필수 여부 | 설명 |
| - | - | - | - |
| `query` | string | ✓ | 1\~128자, 공백으로만 구성될 수 없습니다. `site:`, `-site:`, `"..."`, `lang:`, `after:`, `before:` 및 기타 연산자를 지원합니다 |
| `count` | int | | 1\~50, 기본값 10. 가격에 영향을 주지 않습니다 |
| `need_content` | bool | | 기본값 `false`, `true`인 경우 각 결과에 페이지 본문이 포함됩니다 |
| `ori_question` | string | | 사용자의 원래 질문, 1\~128자 |
| `localization` | string | | **사용자의 IP 주소**(로케일 코드가 아님), 지역 맞춤 순위 지정에 사용됩니다 |

요청 본문에는 `model` 필드가 필요하지 않으며, 알 수 없는 필드는 무시됩니다.

## 응답 하이라이트

```json theme={null}
{
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "short summary, about 100–200 characters",
      "summary": "long summary, about 600–800 characters",
      "content": "",
      "rerank_score": 2.1,
      "authority": 3,
      "date": "2026-10-20T08:00:00Z",
      "site_name": "...",
      "site_icon": "https://..."
    }
  ]
}
```

* 모델에는 `summary`을(를) 전달하고 사람에게는 `snippet`을(를) 보여주십시오. 전체 텍스트의 경우 `need_content`을(를) 활성화하거나 몇 가지 결과를 선택하여 [Fetch](/ko/api-capabilities/deepseek-search-fetch/fetch-api)를 사용하십시오.
* `rerank_score` ≥ 1.5 및 `authority` ≥ 3은 고품질 결과를 나타내며 적절한 필터링 임계값으로 활용하기 좋습니다.
* `count=50`을(를) 사용하면 응답 크기가 약 180 KB이며, `need_content`을(를) 사용하면 두 배 이상 늘어납니다. 이에 맞게 클라이언트 타임아웃을 설정하십시오.

## 오류 코드

| HTTP | 예시 메시지 | 원인 및 해결 방법 | 과금 여부 |
| - | - | - | - |
| 400 | `'count' must be between 1 and 50` | `count` 범위 초과 | 아니요 |
| 400 | `'query' must not be empty` / `missing field 'query'` | `query` 누락 또는 비어 있음 | 아니요 |
| 400 | `'localization' must be a valid IP address` | 로캘 코드가 전달되었습니다. IP를 전송하거나 해당 필드를 제거하십시오 | 아니요 |
| 401 | `Invalid token.` | 유효하지 않은 API 키 또는 `Authorization` 헤더 누락 | 아니요 |
| 429 | — | 업스트림 요청 제한(100 QPS) 초과. 대기 후 다시 시도하십시오 | 아니요 |
| 503 | `no available channels for model deepseek-search` | 해당 키의 그룹에 이 API(예: ClaudeCode)가 포함되어 있지 않습니다. `default` / `svip` 키를 사용하십시오 | 아니요 |
| 5xx / 504 | — | 업스트림 내부 오류 또는 타임아웃 발생. 나중에 다시 시도하십시오 | 아니요 |

오류 본문의 `type`은 항상 `shell_api_error`입니다. HTTP 상태 코드를 기준으로 분기하십시오.


## OpenAPI

````yaml api-reference/deepseek-search-openapi-en.yaml POST /v1/tools/search
openapi: 3.1.0
info:
  title: DeepSeek Web Search API
  description: >
    `deepseek-search` — DeepSeek's native web search API. Returns structured
    search results for a query, built for agents and RAG.


    - Not a chat model and consumes no tokens: **billed per successful
    request**; `count` and `need_content` do not affect the price

    - Parameter errors such as 400 are not billed

    - Upstream rate limit: 100 QPS

    - Available in the `default` / `svip` groups; ClaudeCode group keys cannot
    call it


    **Authentication**: header `Authorization: Bearer YOUR_API_KEY`


    **Get an API key**: create one in the APIYI console at `api.apiyi.com/token`
  version: 1.0.0
servers:
  - url: https://api.apiyi.com
    description: Primary endpoint
security:
  - bearerAuth: []
paths:
  /v1/tools/search:
    post:
      tags:
        - Search & Fetch
      summary: 'Web search: deepseek-search'
      description: >
        Send a query, get 1–50 web search results. The request body does not
        need a `model` field.


        `query` supports search operators: `site:` (join several with `OR`),
        `-site:`, `"..."`, `-"..."`, `-keyword`, `lang:zh,en`, `after:`,
        `before:`.
      operationId: deepseekToolsSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              query: DeepSeek V4 release
              count: 5
      responses:
        '200':
          description: Search succeeded (billed once)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                results:
                  - title: DeepSeek V4 released
                    url: https://example.com/news/deepseek-v4
                    snippet: A short snippet of about 100–200 characters...
                    summary: A long summary of about 600–800 characters...
                    content: ''
                    rerank_score: 2.1
                    authority: 3
                    date: '2026-10-20T08:00:00Z'
                    site_name: Example News
                    site_icon: https://example.com/favicon.ico
        '400':
          description: >-
            Invalid parameters, not billed: `count` outside 1–50, empty or
            missing `query`, `localization` not an IP address, etc.
        '401':
          description: Invalid API key
        '429':
          description: Upstream rate limit exceeded (100 QPS); wait and retry
        '503':
          description: >-
            This API is not enabled for the key's group (e.g. ClaudeCode); use a
            default / svip group key
      security:
        - bearerAuth: []
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: >-
            Search query, 1–128 characters, not all whitespace. Supports site: /
            lang: / after: and other operators
          example: DeepSeek V4 release
        count:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: Number of results, 1–50. Does not affect the price
          example: 5
        need_content:
          type: boolean
          default: false
          description: >-
            Whether to return the page body. When false, content is always an
            empty string
        ori_question:
          type: string
          description: >-
            The user's original question that triggered this search, 1–128
            characters
        localization:
          type: string
          description: >-
            The user's IP address, used to prioritize localized results. **Not a
            locale code**: passing ja-JP returns 400
          example: 8.8.8.8
    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              url:
                type: string
              snippet:
                type: string
                description: Short snippet, about 100–200 characters, for display
              summary:
                type: string
                description: Long summary, about 600–800 characters, for models
              content:
                type: string
                description: Page body; empty string when need_content is false
              rerank_score:
                type: number
                description: Relevance score 0–3; 1.5 or higher is high quality
              authority:
                type: integer
                description: >-
                  Site authority 0–4, -1 = unknown; 3 or higher is highly
                  authoritative
              date:
                type:
                  - string
                  - 'null'
                description: Publication time, UTC RFC 3339
              site_name:
                type:
                  - string
                  - 'null'
              site_icon:
                type:
                  - string
                  - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Add Authorization: Bearer YOUR_API_KEY to the request headers'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.