웹 검색 | everyais

모델이 직접 Google 검색을 실행해 최신 정보로 답합니다 — 검색 쿼리당 과금.

모델이 필요하다고 판단하면 직접 웹 검색을 실행하고 그 결과로 답합니다. 클라이언트가 도구를 실행할 필요는 없습니다 — tools 에 web_search 한 줄만 넣으면 됩니다.

{
  "model": "everyais/gemini-3-6-flash",
  "messages": [{"role": "user", "content": "오늘 서울 날씨 알려줘"}],
  "tools": [{"type": "web_search"}]
}

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

지원 모델

GET /v1/models 의 capabilities.web_search 로 확인하세요 — 목록이 유일한 정답입니다. Gemini 계열이라고 전부 되는 것이 아니며, 같은 세대 안에서도 모델마다 갈립니다. 작성 시점(2026-08) 기준으로는 everyais/gemini-3-6-flash 한 종입니다.

curl https://api.everyais.com/v1/models \
  -H "Authorization: Bearer $EVERYAIS_API_KEY" \
  | jq '.data[] | select(.capabilities.web_search) | .id'

지원하지 않는 모델에 web_search 를 보내면 프로바이더를 호출하기 전에 400 web_search_unsupported_model 을 반환합니다(과금 없음).

web_search 는 tools 배열에 최대 1개만 넣을 수 있습니다(2개 이상은 400).
function 도구와 함께 쓸 수 있습니다. tool_choice 는 function 도구에만 적용됩니다.
/v1/chat/completions 전용입니다 — /v1/messages · /v1/responses 는 아직 지원하지 않습니다.

⚠️ 과금은 요청당이 아니라 검색 쿼리당입니다

모델은 한 요청에서 검색을 여러 번 실행할 수 있습니다. "A와 B를 비교해줘" 라는 질문 하나에 모델이 A 검색·B 검색 두 쿼리를 돌리면 2건이 청구됩니다. 요청 1건 = 검색 1건이 아닙니다.

검색 비용 = 실행된 검색 쿼리 수 × 쿼리당 단가 이며, 토큰 과금과 별도로 합산됩니다.
검색으로 가져온 본문은 입력 토큰으로 과금되지 않습니다.
모델이 검색이 필요 없다고 판단하면 쿼리 수는 0 이고 검색 과금도 0 입니다.
실제 과금된 쿼리 수는 응답의 x_everyais.web_search.billed_queries 로 확인하세요. 비스트림 응답의 x-everyais-cost-usd 헤더에는 검색 비용이 포함된 총액이 담깁니다.

쿼리 수를 강제로 제한하는 파라미터는 없습니다(프로바이더가 제공하지 않습니다). 지출을 통제하려면 API 키의 월/일 지출 한도를 사용하세요.

응답에서 출처 읽기

{
  "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_html`	Google 이 제공하는 검색 제안 HTML

⚠️ search_entry_point_html 은 Google 이 표시를 요구하는 HTML 입니다. 검색 결과를 화면에 노출하는 서비스라면 그대로 렌더해야 합니다. 신뢰할 수 없는 외부 HTML 이므로 <iframe sandbox srcdoc="..."> 처럼 격리해서 넣으세요.

스트리밍

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

본문 delta.content 청크들
delta.annotations 청크 1개 (finish 직전)
finish_reason 청크
usage 청크(choices: []) — 여기에 x_everyais.web_search 가 실립니다

출처는 본문이 다 모인 뒤에야 인덱스를 확정할 수 있어 마지막에 한 번만 옵니다. 검색 쿼리 수도 마지막 usage 청크에만 있으므로, 비용을 대조하려면 스트림을 끝까지 읽으세요.