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.10 / 회 검색
검색 결과 토큰	사용 모델의 표준 input 단가

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

비용 절감 3가지 방법:

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

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

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

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

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

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

OpenAI 호환 엔드포인트 사용

/v1/chat/completions(OpenAI 형식)를 사용하는 경우, 동작은 키가 바인딩된 채널에 따라 다릅니다. OpenRouter로 프록시하는 채널은 해당 업스트림의 검색 도구 구문을 사용하세요(예: tools:[{"type":"openrouter:web_search"}]). 다른 경우에는 호환성이 가장 좋은 /v1/messages + synthorai:web_search를 권장합니다. 키에 맞는 최적 방법은 문의해 주시면 확인해 드립니다.

자주 묻는 질문

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

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

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

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

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

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