everyais
← 문서 목록

가이드

웹 검색

업데이트

tools에 {"type": "web_search"}를 넣으면 모델이 필요할 때 웹을 검색해 답합니다. 검색은 서버에서 실행되므로 클라이언트는 도구를 실행하지 않습니다.

python
response = client.chat.completions.create(
    model="everyais/gemini-3-8-flash",
    messages=[{"role": "user", "content": "오늘 서울 날씨 알려줘"}],
    tools=[{"type": "web_search"}],
)

지원 모델

GET /v1/models에서 capabilities.web_search가 true인 모델만 쓰세요. 같은 Gemini 계열이어도 모델마다 다릅니다.

bash
curl https://api.everyais.com/v1/models \
  -H "Authorization: Bearer $EVERYAIS_API_KEY" \
  | jq '.data[] | select(.capabilities.web_search) | .id'
  • 지원하지 않는 모델은 400 web_search_unsupported_model이고 요금은 청구되지 않습니다.
  • web_search는 tools에 하나만 넣을 수 있습니다. 두 개 이상이면 400입니다.
  • function 도구와 함께 쓸 수 있습니다. tool_choice: "none"이면 둘 다 꺼집니다. 검색 도구만 있는데 required나 특정 함수를 지정하면 400입니다.
  • /v1/chat/completions에서만 지원합니다.

검색 요금

토큰 요금에 billed_queries × 검색 단가가 더해집니다.

모델 계열청구 건수
Gemini실행한 검색 쿼리마다 1건. 두 번 검색하면 2건, 검색하지 않으면 0건
  • 토큰이 무료인 모델(pricing.is_free)도 검색 요금은 청구됩니다.
  • 스트리밍을 중간에 끊어도 Google이 실행한 검색은 청구됩니다. 실제 건수는 답변 끝에 오므로 끊긴 뒤 최대 10초 기다려 확인하고, 그때까지 오지 않으면 요청 때 예약한 10건으로 청구합니다.
  • Google 검색으로 가져온 본문은 입력 토큰으로 청구하지 않습니다.
  • 스트리밍이 아니면 x-everyais-cost-usd 헤더에 검색 요금을 포함한 총액이 있습니다.
  • 검색 횟수를 제한하는 파라미터는 없습니다. 지출은 API 키의 지출 한도로 제한하세요.

응답의 출처

json
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "오늘 서울은 맑고 최고기온 28도입니다.",
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "url": "https://...",
            "title": "서울 날씨",
            "start_index": 0,
            "end_index": 24
          }
        }
      ]
    },
    "finish_reason": "stop"
  }],
  "x_everyais": {
    "web_search": {
      "queries": ["오늘 서울 날씨"],
      "search_entry_point_html": "<div>...</div>",
      "billed_queries": 1
    }
  }
}
필드내용
message.annotations[]OpenAI url_citation 형식의 출처. start_index·end_index는 content의 문자 위치입니다
x_everyais.web_search.queries모델이 실행한 검색어
x_everyais.web_search.billed_queries청구된 검색 건수
x_everyais.web_search.search_entry_point_htmlGoogle이 제공하는 검색 제안 HTML

검색 결과를 화면에 보여 준다면 Google 정책에 따라 search_entry_point_html도 함께 표시해야 합니다. <iframe sandbox srcdoc="...">처럼 격리해서 넣으세요.

스트리밍

stream: true면 출처와 검색 정보가 본문 다음에 옵니다.

  1. 본문 delta.content 청크
  2. delta.annotations 청크 1개(종료 직전)
  3. finish_reason 청크
  4. 사용량 청크(choices: []). x_everyais.web_search가 여기에 있습니다

검색 건수는 마지막 사용량 청크에만 있으니, 비용을 확인하려면 스트림을 끝까지 읽으세요.

문의접수