Valyu TypeScript SDK (valyu-js)의 개요
valyu-js는 AI 에이전트용 검색 API인 Valyu의 공식 TypeScript 및 JavaScript 클라이언트입니다. `Valyu` 객체 하나로 웹과 독점 소스(PubMed, arXiv, SEC 제출 서류, 특허 등) 검색, URL 콘텐츠 추출, 근거 기반 답변, 그리고 DeepResearch를 다룹니다. DeepResearch는 비동기 조사 에이전트로, 출처가 달린 보고서와 선택적으로 PDF, CSV 등의 파일을 돌려줍니다.
`npm install valyu-js`로 설치하고 `VALYU_API_KEY`를 넘깁니다. 현재 버전은 2.11.5로, 2026년 10월 31일 npm에 게시되었습니다. SDK는 MIT이지만 SDK가 하는 모든 호출은 Valyu 크레딧으로 과금됩니다.
Valyu TypeScript SDK (valyu-js), 쓸 만한 가치가 있습니까?
valyu-js는 잘 관리되는 래퍼이며, 그 가치는 뒤에 있는 Valyu API에 따라 오르내립니다. SDK 자체는 MIT로 무료지만 키 없이는 아무것도 하지 못하고, 모든 검색, 추출, 조사 작업은 크레딧으로 과금됩니다. 도입 전에 답해야 할 질문은 클라이언트가 좋은지가 아니라, 여러분의 쿼리에서 Valyu의 데이터가 Exa, Tavily 또는 직접 운영하는 크롤러보다 나은지입니다.
클라이언트는 좋습니다. changelog를 읽어 보면 2.11.0부터 2.11.5까지가 짧은 간격으로 나왔고, `instant` 조사 모드, 429 응답 시 자동 재시도(기본 2회, Retry-After를 최대 60초까지 따름), DeepResearch 요청의 120초 타임아웃, ETag 기반 폴링, `contents()`의 페이지별 캐시 제어가 추가되었습니다. 여러 수정은 `countryCode`를 잘못된 표기로 보내던 것처럼 SDK가 조용히 버리던 옵션에 관한 것이었습니다. 이런 솔직함은 안심이 되며, 최신 버전을 유지할 이유이기도 합니다.
DeepResearch는 모드별 작업 단위로 과금됩니다. instant 8크레딧, fast 25, standard 100, heavy 500, max 2,500이며 검색과 페이지 읽기가 포함됩니다. 종량제 단가인 $10에 1,600크레딧 기준으로 fast 작업은 약 $0.16, max 작업은 약 $15.60입니다. TypeScript SDK의 기본값은 fast이고 API와 Python SDK의 기본값은 standard이므로, 같은 호출도 다른 클라이언트에서는 네 배가 들 수 있습니다. 결과물 파일은 첫 번째 이후 하나당 16크레딧입니다. 검색은 소스별로 결과 1,000건당 과금되며 arXiv와 PubMed는 약 $0.31, 웹은 $0.63, 라이선스 학술지는 최대 $30입니다.
주의할 점: 채택의 증거는 적고 대부분 자기 진영의 것입니다. 저장소의 GitHub 별은 2개이고, npm은 2026년 11월 2일까지 30일 동안 19,281회 다운로드를 집계했습니다. 눈에 보이는 오픈소스 사용 사례는 Global Threat Map, Global Hack Map, Polyseer 등 Valyu와 가까운 사람들의 데모 앱입니다. 이는 API가 그 앱들에서 작동한다는 증거일 뿐 시장 점유율의 증거는 아닙니다. 또한 키는 과금 자격 증명입니다. SDK는 서버 코드용이며, `VALYU_API_KEY`가 포함된 브라우저 번들은 개발자 도구를 여는 누구에게나 크레딧 잔액을 넘겨주게 됩니다.
결론: valyu-js는 Valyu를 시험해 보는 비용으로 보면 되고, 그 비용은 낮습니다. Valyu 자체는 제품에 넣기 전에 여러분의 쿼리 표본으로 평가해야 합니다.
제 역할을 하는 곳
Next.js로 바이오테크 문헌 어시스턴트를 만드는 2인 스타트업
스크레이퍼를 유지하지 않고 서버에서 PubMed와 임상시험을 검색하고 싶다
API 라우트에서 `searchType: "proprietary"`와 PubMed로 제한한 `includedSources`로 `valyu.search()`를 호출합니다. 결과는 반환된 1,000건당 과금되며 PubMed는 약 $0.31이므로, 시제품은 가입 시 받는 $10 크레딧으로 충분합니다.
소규모 펀드의 주식 애널리스트
매일 아침 한 기업에 대한 출처 달린 초안을 받고 싶다
`batch`로 fast 모드 `deepresearch.create()` 작업을 건당 25크레딧(종량제로 약 $0.16)에 대기열에 넣고 markdown이나 PDF 출력을 읽습니다. heavy 모드는 보고서당 500크레딧이므로 모드 선택이 청구액을 좌우합니다.
사내 에이전트에 웹 읽기 기능을 추가하는 플랫폼 엔지니어
URL 목록을 깔끔한 텍스트나 JSON 필드로 바꾸고 싶다
`contents()`는 동기 방식으로 1~10개, 비동기 방식으로 최대 50개의 URL을 받으며, 구조화 추출용 JSON 스키마와 새 크롤링을 강제하는 `maxAge`를 지정할 수 있습니다. 서버에서만 실행하고 키는 비밀 저장소에 보관합니다.
도입 전 확인할 점
- 설정
- `npm install valyu-js`를 실행하고 `VALYU_API_KEY`를 설정한 뒤 `new Valyu(process.env.VALYU_API_KEY)`를 호출합니다. 첫 검색까지 몇 분이면 되고, 가입에 카드가 필요 없습니다.
- 연동
- 같은 API를 Python SDK로도 쓸 수 있습니다. README에는 Vercel AI SDK(@valyu/ai-sdk), LangChain, MCP 연동이 나와 있습니다. 모든 요청과 응답의 TypeScript 타입이 내보내집니다.
- 데이터와 개인정보
- 쿼리와 URL은 Valyu의 호스팅 API로 전송되며, SDK에는 자체 호스팅 모드가 없습니다. Valyu의 데이터 보존 및 학습 사용 조건은 SDK 문서에서 다루지 않습니다. DeepResearch 다운로드 링크는 서명되어 있고 만료됩니다.
- 대규모 사용 시 비용
- 월 요금제는 $29에 5,000크레딧, $99에 18,000, $499에 100,000이며 크레딧은 이월되지 않습니다. 잔액이 0이 되면 초과 요금을 청구하는 대신 새 요청이 402를 반환합니다. 문서에 따르면 DeepResearch 동시 실행 수는 요금제에 따라 다르며, 종량제는 동시에 2개, $29 요금제는 5개입니다.
- 제한
- 검색은 호출당 최대 20개 결과를 반환합니다. DeepResearch의 하드 시간 제한은 2분(instant)부터 90분(max)까지이며, `wait()`는 2시간 후 포기합니다. 요청 수에 대한 수치 레이트 리밋은 공개되어 있지 않습니다.
좋은 점
- search, contents, answer, DeepResearch, batch, workflows를 하나의 타입 클라이언트로 제공
- 429 시 안전한 자동 재시도, 서버의 Retry-After 준수
- 잦은 릴리스와 상세하고 솔직한 changelog
- MIT 라이선스
아쉬운 점
- 유료 종량제 Valyu 계정 없이는 쓸모없음
- TypeScript 기본 모드(fast)가 API 기본값(standard)과 다름
- Valyu와 가까운 데모 앱 외에는 독립적인 채택이 적음
- 최근 수정 여러 건이 이전에 오류 없이 버려지던 옵션에 관한 것
추천 대상
Valyu의 데이터 소스가 자신들의 에이전트에 맞는다고 이미 판단했고, 공식적으로 관리되는 클라이언트를 원하는 TypeScript 팀.
Valyu TypeScript SDK (valyu-js) 대안
Valyu TypeScript SDK (valyu-js): 자주 묻는 질문
- Valyu TypeScript SDK (valyu-js), 쓸 만한 가치가 있습니까?
- 유료 API 하나를 위한 꼼꼼하고 빠르게 발전하는 클라이언트입니다. 코드는 MIT이지만 실제로 사는 것은 Valyu의 크레딧 계량기입니다. 평점은 5점 만점에 3.8점입니다.
- Valyu TypeScript SDK (valyu-js)의 가격은 얼마입니까?
- SDK는 MIT로 무료입니다. Valyu API는 크레딧 단위 종량제입니다. 종량제는 $10에 1,600크레딧, 월 요금제는 $29, $99, $499입니다. 신규 계정은 $10 무료 크레딧(회사 이메일로 가입 시 $20)을 받습니다.
- Valyu TypeScript SDK (valyu-js)의 단점은 무엇입니까?
- 유료 종량제 Valyu 계정 없이는 쓸모없음; TypeScript 기본 모드(fast)가 API 기본값(standard)과 다름; Valyu와 가까운 데모 앱 외에는 독립적인 채택이 적음; 최근 수정 여러 건이 이전에 오류 없이 버려지던 옵션에 관한 것.
- Valyu TypeScript SDK (valyu-js)에 적합한 사람은 누구입니까?
- Valyu의 데이터 소스가 자신들의 에이전트에 맞는다고 이미 판단했고, 공식적으로 관리되는 클라이언트를 원하는 TypeScript 팀.
- 팀이나 프로덕션 환경에서 Valyu TypeScript SDK (valyu-js)의 비용은 얼마입니까?
- 월 요금제는 $29에 5,000크레딧, $99에 18,000, $499에 100,000이며 크레딧은 이월되지 않습니다. 잔액이 0이 되면 초과 요금을 청구하는 대신 새 요청이 402를 반환합니다. 문서에 따르면 DeepResearch 동시 실행 수는 요금제에 따라 다르며, 종량제는 동시에 2개, $29 요금제는 5개입니다.
- Valyu TypeScript SDK (valyu-js)에 회사 데이터를 맡겨도 안전합니까?
- 쿼리와 URL은 Valyu의 호스팅 API로 전송되며, SDK에는 자체 호스팅 모드가 없습니다. Valyu의 데이 터 보존 및 학습 사용 조건은 SDK 문서에서 다루지 않습니다. DeepResearch 다운로드 링크는 서명되어 있고 만료됩니다.
- Valyu TypeScript SDK (valyu-js)의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 Firecrawl, Crawl4AI 및 GPT Researcher입니다.
답변 확인일: 2026년 11월 3일.