Web Fetch

이미 URL을 아는 페이지의 전문을 모델에 제공합니다. 도구 항목 하나만 추가하면 Synthorai가 페이지를 가져와 정리하고 읽기 좋은 본문을 대화에 넣습니다 — 어떤 모델, 어떤 채널이든.

최소 요청

/v1/messages의 tools에 synthorai:web_fetch를 추가하세요. 다른 것은 그대로입니다:

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_fetch"}],
    "messages": [
      {"role": "user", "content": "Summarise https://docs.anthropic.com/en/docs/build-with-claude/tool-use"}
    ]
  }'

ℹ

모델이 필요하다고 판단하고 사용자가 synthorai:web_fetch를 포함했을 때만 페이지를 가져옵니다. 도구가 없는 요청은 평범한 요청입니다 — 동작에도 비용에도 영향이 없습니다.

옵션

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

매개변수	설명
`max_uses`	한 요청에서 가져올 최대 페이지 수. 기본 3, 상한 10. 이는 지출 한도이므로 재시도를 가로질러 강제됩니다 — `max_uses: 1`을 선언한 요청은 채널을 넘나들며 재시도되어도 최대 한 번의 가져오기만 과금됩니다.

{
  "type": "synthorai:web_fetch",
  "max_uses": 2
}

Web Search와 함께 쓰기

검색은 페이지를 찾고 가져오기는 페이지를 읽습니다. 둘 다 선언하면 모델이 검색해서 유망한 결과를 고르고 페이지 전체를 끌어올 수 있습니다 — 리서치형 질문에는 보통 그것이 원하는 동작입니다:

"tools": [
  {"type": "synthorai:web_search"},
  {"type": "synthorai:web_fetch"}
]

응답 형태

각 가져오기는 assistant 턴에 블록 한 쌍으로 나타나고 그 뒤에 모델의 답변이 이어집니다:

{
  "type": "server_tool_use",
  "id": "srvtoolu_synth_...",
  "name": "web_fetch",
  "input": { "url": "https://example.com/page" }
},
{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_synth_...",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/page",
    "title": "Example page",
    "content": { "type": "text", "text": "…page body…" }
  }
}

가져오기 횟수는 usage에 보고되므로 요금을 직접 대조할 수 있습니다:

"usage": {
  "input_tokens": 9241,
  "output_tokens": 412,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "server_tool_use": { "web_fetch_requests": 1 }
}

과금

항목	가격
가져온 페이지당	$0.01 / 회
토큰(프롬프트 + 컴플리션)	사용 모델의 표준 input 단가

!
가져오기당 요금이 전체 비용은 아닙니다. 가져온 페이지는 입력 토큰으로 대화에 들어가며 긴 글은 수천 토큰이 될 수 있습니다 — 대부분의 모델에서 그 토큰 비용이 $0.01 요금을 넘습니다. 둘 다 예산에 넣으세요.

예측 가능하게 유지하는 세 가지 방법:

max_uses를 작업에 필요한 최솟값으로 설정하세요 — 재시도를 포함해 요청 전체의 요금 상한이 됩니다.

모델이 탐색하게 두지 말고 특정 페이지를 가져오게 하세요. 사용자가 붙여넣은 URL은 한 번의 가져오기지만 "주제 주변을 읽기"는 세 번이 될 수 있습니다.

usage.server_tool_use.web_fetch_requests와 usage.input_tokens를 함께 지켜보세요 — 돈은 보통 후자에서 나갑니다.

제한과 안전

http와 https URL만 가져옵니다. 자격 증명이 포함된 URL은 거부됩니다.

사설, 루프백, 링크-로컬, 클라우드 메타데이터 주소는 거부됩니다 — web_fetch는 공개 페이지에만 도달합니다.

페이지 본문은 대화에 들어가기 전 설정된 문자 한도로 잘리므로 거대한 페이지 하나가 요청 하나를 무한정 부풀릴 수 없습니다.

가져올 수 없는 페이지는 전체 요청을 실패시키지 않고 오류 블록으로 돌아오며, 모델은 이에 반응하거나 페이지 없이 답할 수 있습니다.

synthorai:web_fetch를 선언하는 동안 순수 이름 web_fetch는 예약됩니다 — 그 이름으로 자체 도구를 선언하면 이름을 명시한 400이 반환됩니다. 이름을 바꾸거나 synthorai: 파라미터를 제거하세요.

저희 네트워크를 떠나기 전에 거부된 가져오기 — 거부된 URL, 차단된 도메인, 미구성 백엔드 — 는 과금되지 않습니다. 공급자에 도달해 거기서 실패한 가져오기는 공급자가 저희에게 청구하므로 과금됩니다. 둘 다 max_uses에는 계산됩니다.

가져오는 것에 대한 사용자의 책임

web_fetch는 사용자의 지시로 페이지를 가져옵니다. 어떤 URL을 가져올지 사용자가 결정하므로 그 검색과 돌아온 것의 활용은 사용자의 책임입니다.

콘텐츠에 접근할 권리는 사용자에게 있어야 합니다. 대상 사이트의 이용약관, robots.txt, 페이월이나 로그인 경계, 적용되는 저작권 및 데이터베이스권을 포함합니다. 저희를 통한 가져오기가 원래 없던 접근 권한을 부여하지 않습니다.

개인정보는 여전히 사용자의 의무입니다. 가져온 페이지에 개인정보가 있다면 GDPR, PIPL 및 동등 제도 하에서 사용자가 계속 그 컨트롤러입니다 — 법적 근거, 보존, 삭제 요청 대응을 포함해서요.

가져오기에서 비롯된 청구는 사용자의 몫입니다. 권리자나 사이트 운영자가 사용자가 가져온 콘텐츠에 대해 청구를 제기하면 그 청구는 사용자를 향하며 비용도 사용자가 부담합니다. 이는 저희가 경유하는 업스트림 검색 공급자의 약관과 같은 구조입니다.

모델 출력이 재사용 허가를 받은 것은 아닙니다. 가져온 자료에 기반한 모델 답변은 그 일부를 재현할 수 있습니다. 그 출력을 재게시할 수 있는지는 출처의 라이선스 문제이며 저희는 이에 대해 어떤 진술도 하지 않습니다.

저희가 맡는 것: 검색 인프라 운영, 내부 및 사설 네트워크 주소 차단, 관리자가 구성한 도메인 차단 목록 준수, 요청 처리를 넘어선 페이지 콘텐츠 비보존. 개별 URL의 적법성은 심사하지 않으며 할 수도 없습니다 — URL 자체는 라이선스를 담고 있지 않습니다.

!
신뢰할 만한 남용 신고를 받거나 검색 공급자가 플래그한 API 키의 web_fetch는 중단합니다. 공급자 계정이 정지되면 모든 고객의 기능이 함께 내려가기 때문입니다.

FAQ

제가 언급하지 않은 페이지를 모델이 가져올 수 있나요?

같은 대화에서 synthorai:web_search로 찾은 URL을 따라갈 수 있으며, 그것이 둘을 결합하는 이유입니다. URL을 지어내지 않도록 지시되어 있고, 페이지를 찾아야 한다면 먼저 검색해야 합니다.

페이지가 로그인 뒤에 있거나 크롤러를 차단하면 어떻게 되나요?

해당 가져오기에 대한 오류 블록을 받고 모델은 그 페이지 없이 계속합니다. 요청이 실제로 사용자를 대신해 이루어졌으므로 그 가져오기는 max_uses에 계산됩니다.

페이지를 가져오지 않으면 도구 선언이 무언가를 바꾸나요?

아니요. 모델이 실제로 무언가를 가져오기 전까지 과금과 동작은 일반 요청과 동일합니다.