Web Search

Claude가 실시간으로 웹을 검색하며 답변할 수 있게 합니다. 최신 뉴스, 가격, 버전, 일정, 학습 데이터 이후의 사실 조회에 유용합니다.

빠른 시작

/v1/messages 요청의 tools 배열에 항목 하나를 추가하면 됩니다. 모델이 검색 여부, 검색 내용, 검색 횟수를 스스로 결정합니다:

curl https://synthorai.io/v1/messages \
  -H "x-api-key: $YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "tools": [{"type": "synthorai:web_search"}],
    "messages": [
      {"role": "user", "content": "What is the latest Claude model?"}
    ]
  }'

ℹ

tools에 synthorai:web_search를 명시적으로 추가한 경우에만 웹 검색이 실행됩니다. 추가하지 않은 요청은 일반 요청이며 동작과 비용에 영향이 없습니다.

선택적 파라미터

synthorai:web_search 항목의 모든 필드는 선택 사항입니다:

매개변수	설명
`max_uses`	요청당 최대 검색 라운드 수(비용 관리용). 생략하면 플랫폼 기본값 사용.
`allowed_domains`	이 도메인 내에서만 검색합니다(예: `["arxiv.org","github.com"]`).
`blocked_domains`	이 도메인을 검색 결과에서 제외합니다.

{
  "type": "synthorai:web_search",
  "max_uses": 3,
  "allowed_domains": ["anthropic.com", "openai.com"]
}

응답 구조

검색이 포함된 응답의 content에는 다음 블록 유형이 순서대로 포함됩니다:

server_tool_use - 모델이 발행한 검색 쿼리.
web_search_tool_result - 검색 결과(제목, URL, 스니펫).
text - 결과를 기반으로 한 최종 답변(출처 인용 포함).

usage 객체에 실행된 검색 횟수를 알려주는 추가 필드가 포함됩니다:

"usage": {
  "input_tokens": 14577,
  "output_tokens": 331,
  "server_tool_use": { "web_search_requests": 2 }
}

과금

항목	가격
검색 요금	$0.01 / 회 검색
검색 결과 토큰	사용 모델의 표준 input 단가

과금은 두 부분으로 구성됩니다: 실행된 검색당 $0.01, 그리고 반환된 웹 콘텐츠가 input 토큰으로 과금됩니다(검색 1회당 약 7,000~14,000 토큰). 검색이 포함된 요청은 일반 요청보다 눈에 띄게 비쌉니다 - max_uses로 검색 횟수를 제한하세요.

비용 절감 3가지 방법:

max_uses를 설정해 검색 라운드 수를 제한합니다.

프롬프트 캐싱을 활용합니다(cache_control 사용 시 결과가 캐시되어 멀티턴 대화에서 크게 절약됩니다).

allowed_domains로 검색 범위를 좁힙니다.

참고 벤치마크(claude-sonnet-4-6, 캐시 없음):

경량(검색 2회, 사실 확인): ≈ $0.07 / 요청

중량(검색 8회, 리서치): ≈ $0.33 / 요청

OpenAI 호환 엔드포인트 사용

synthorai:web_search는 /v1/chat/completions와 /v1/responses에서도 동작합니다. /v1/messages에 보내던 것과 같은 선언을 그대로 쓰면 됩니다. 엔드포인트별로 무엇을 돌려주는지: OpenAI 호환 두 엔드포인트에서는 검색한 출처가 OpenAI의 annotations(url_citation 형태)로 돌아옵니다 - chat completions는 메시지에, responses는 output_text 항목에 붙습니다. /v1/messages에서는 같은 검색이 server_tool_use와 web_search_tool_result 블록으로 돌아옵니다. 모든 엔드포인트에서 응답의 usage는 검색이 거친 모든 라운드를 포함하므로, 청구되는 토큰과 보이는 토큰이 같습니다. OpenRouter로 프록시하는 채널은 해당 업스트림의 검색 도구 문법(예: tools:[{"type":"openrouter:web_search"}])을 써도 됩니다. synthorai: 파라미터는 /v1/messages, /v1/chat/completions, /v1/responses에서 허용됩니다 - Gemini 계열 엔드포인트로 보내면 모델이 모르는 도구를 업스트림으로 그대로 흘리는 대신 그 사실을 설명하는 400을 돌려줍니다. 확실하지 않으면 문의해 주세요. 사용 중인 키에 맞는 방법을 확인해 드립니다.

예약된 도구 이름

synthorai:web_search를 선언하는 동안 순수 이름 web_search는 예약되어 있습니다. 이 이름으로 자체 도구를 선언하면 해당 이름을 명시한 400이 반환됩니다. 도구 이름을 바꾸거나 synthorai: 매개변수를 제거하세요. 저희가 바로 그 이름으로 검색 도구를 주입하므로, 같은 이름의 도구 두 개가 모델에 도달하면 어느 쪽의 호출이 돌아온 것인지 판별할 수 없습니다. synthorai: 매개변수 없이 이 이름으로 자체 도구를 사용하는 것은 영향을 받지 않습니다 - 아무것도 주입하지 않으므로 충돌하지 않습니다.

자주 묻는 질문

Claude Code / Anthropic SDK를 사용하는데 이용할 수 있나요?

네. /v1/messages 엔드포인트에 synthorai:web_search를 사용하면 됩니다. 순수 OpenAI 형식 릴레이 채널에 바인딩된 키의 경우 네이티브 검색 도구가 작동하지 않을 수 있으며, 이 경우 전용 채널을 설정해 드립니다.

검색에 실패하면 어떻게 되나요?

실패한 검색 라운드는 과금되지 않습니다. 모델은 실패 신호를 받고 다른 쿼리로 재시도하거나 기존 지식을 바탕으로 답변합니다. 전체 요청이 오류가 되지는 않습니다.

요청하지 않아도 웹 검색이 실행되나요?

아니요. tools 배열에 synthorai:web_search를 명시적으로 추가한 경우에만 웹 검색이 활성화됩니다. 일반 요청은 절대 웹 검색을 실행하지 않습니다.