웹 검색 | everyais

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

json

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

python

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 및 Z.AI 계열에서도 지원 여부는 모델마다 다릅니다. 현재 카탈로그에서 확인하세요. 예제 모델의 현재 지원 여부도 위 필드로 확인하고, 지원 모델이 바뀌면 모델 ID를 교체하세요.

bash

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: "none"은 함수와 웹 검색을 모두 비활성화합니다. 검색 도구만 있을 때 required 또는 특정 함수 지정은 400입니다.
/v1/chat/completions 전용입니다 — /v1/messages · /v1/responses 는 아직 지원하지 않습니다.

공급자별 검색 과금

Google Gemini는 실행된 검색 쿼리당 과금합니다. 한 요청에서 A 검색·B 검색 두 쿼리를 실행하면 2건이 청구됩니다. 모델이 검색하지 않으면 검색 과금은 0입니다.

Z.AI는 웹 검색을 활성화한 성공 요청마다 1건을 과금합니다. 검색 결과가 없거나 모델이 검색하지 않아도 billed_queries = 1 입니다. 토큰 무료 모델도 이 검색 비용은 별도로 청구됩니다.

검색 비용 = billed_queries × 검색 단가 이며, 토큰 과금과 별도로 합산됩니다.
pricing.is_free 는 입력·출력·캐시 토큰만 무료로 만들고 검색 요금은 면제하지 않습니다.
Google 검색으로 가져온 본문은 입력 토큰으로 과금되지 않습니다.
실제 과금된 쿼리 수는 응답의 x_everyais.web_search.billed_queries 로 확인하세요. 비스트림 응답의 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`	검색 과금 건수. Google은 실행 쿼리 수, Z.AI는 검색 활성화 성공 요청당 1
`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 청크에만 있으므로, 비용을 대조하려면 스트림을 끝까지 읽으세요.