AI 에이전트에게 "이 웹페이지 읽어봐"라고 시키면 어떤 일이 벌어질까. HTML 태그, 광고 배너, 네비게이션 바, JavaScript 코드가 뒤섞인 쓰레기 더미를 통째로 삼키게 된다. 토큰은 낭비되고, 엉뚱한 정보가 추출되며, 응답 품질은 곤두박질친다.
이 문제를 한 줄의 URL 프리픽스로 해결하는 도구가 바로 r.jina.ai다. Jina AI가 만든 Reader API는 웹페이지 URL 앞에 https://r.jina.ai/만 붙이면 광고, 스크립트, 마크업을 전부 걷어내고 LLM이 바로 소화할 수 있는 깨끗한 마크다운으로 변환해준다. 가입도 설치도 필요 없다.
이 글에서는 Reader API의 핵심 작동 원리부터 실전 사용법, 고급 헤더 옵션, 요금 체계, 그리고 Firecrawl·Bright Data 같은 경쟁 도구와의 차이점까지 실무에 필요한 모든 정보를 정리한다.
| 핵심 항목 | 내용 |
|---|---|
| 서비스명 | Jina Reader API (r.jina.ai) |
| 개발사 | Jina AI (2020년 설립, 검색 AI 전문) |
| 핵심 기능 | URL → LLM 친화 마크다운/JSON 변환 |
| 무료 사용 | API 키 없이 즉시 가능 (분당 20회) |
| API 키 등록 시 | 1,000만 토큰 무료 제공 (비상업용) |
| 유료 요금 | 100만 토큰당 0.045 - 0.05달러 |
| 지원 포맷 | 웹페이지, PDF, SPA, iframe, Shadow DOM |
| 오픈소스 | Apache-2.0 라이선스 (GitHub 공개) |
| 검색 엔드포인트 | s.jina.ai (웹 검색 + 상위 5개 결과 자동 추출) |
Reader API가 해결하는 근본 문제
웹 콘텐츠는 인간의 눈을 위해 설계되었지, AI를 위해 만들어진 게 아니다. 일반적인 웹페이지 하나를 열어보면 실제 본문은 전체 HTML의 20 - 30%에 불과하다. 나머지 70 - 80%는 광고 코드, CSS 스타일시트, JavaScript 번들, 쿠키 배너, 소셜 공유 버튼 같은 노이즈로 채워져 있다.
LLM에 이 HTML을 그대로 넣으면 문제가 겹겹이 쌓인다. 첫째, 토큰 낭비가 심각하다. GPT-4나 Claude 같은 모델의 컨텍스트 윈도우는 유한한 자원인데, 불필요한 태그가 그 공간을 잠식한다. 둘째, 모델이 본문과 노이즈를 구분하지 못해 정확도가 떨어진다. 셋째, JavaScript로 렌더링되는 SPA(싱글 페이지 앱)는 아예 빈 HTML만 돌아오는 경우도 흔하다.
Jina Reader API는 이 간극을 메우는 번역기 역할을 한다. 내부적으로 Puppeteer 기반 헤드리스 Chrome 브라우저를 돌려 JavaScript 렌더링까지 완료한 뒤, 본문만 정밀하게 추출하여 마크다운으로 변환한다. 웹의 언어를 AI의 언어로 바꿔주는 것이다.
Reader API는 웹페이지뿐 아니라 PDF 파일도 지원한다. 학술 논문이나 보고서 URL을 그대로 넣으면 이미지가 많은 다단 구조 문서에서도 텍스트를 추출하고 차트까지 설명해준다. NASA 논문을 넣었더니 깔끔하게 변환되었다는 사례가 공식 문서에 기록되어 있다.
기본 사용법 3단계 — 브라우저부터 코드까지
Reader API의 가장 큰 매력은 진입 장벽이 사실상 제로라는 점이다. SDK 설치도, 라이브러리 임포트도 필요 없다. 세 가지 방법으로 바로 쓸 수 있다.
브라우저에서 바로 쓰기
가장 간단한 방법이다. 브라우저 주소창에 읽고 싶은 웹페이지 URL 앞에 https://r.jina.ai/를 붙여 넣으면 된다. 예를 들어 위키피디아 인공지능 문서를 변환하고 싶다면 주소창에 아래와 같이 입력한다.
https://r.jina.ai/https://en.wikipedia.org/wiki/Artificial_intelligence
엔터를 치면 브라우저에 마크다운 형식의 깔끔한 텍스트가 즉시 출력된다. 이걸 그대로 복사해서 ChatGPT, Claude 등 어떤 AI에든 붙여넣으면 된다.
curl 명령어로 쓰기
코드에서 사용하려면 curl 한 줄이면 충분하다.
curl https://r.jina.ai/https://example.com
JSON 형식으로 응답을 받고 싶다면 Accept 헤더를 추가한다.
curl -H "Accept: application/json" https://r.jina.ai/https://example.com
JSON 응답에는 url, title, content 세 가지 필드가 포함된다.
Python에서 쓰기
Python requests 라이브러리로도 동일하게 호출할 수 있다. requests.get('https://r.jina.ai/https://example.com') 한 줄이면 response.text에 마크다운이 담겨 온다. API 키가 있다면 헤더에 Authorization: Bearer {API_KEY}를 추가해 레이트 리밋을 높일 수 있다.
결과를 파일로 저장하려면 curl에 -o 옵션을 쓴다. curl https://r.jina.ai/https://example.com -o result.md 처럼 하면 result.md 파일로 바로 떨어진다. PDF URL도 동일하게 작동한다.
웹 검색 엔드포인트 (s.jina.ai)
Reader API에는 URL 변환 외에도 웹 검색 기능이 별도 엔드포인트로 존재한다. https://s.jina.ai/ 뒤에 검색 쿼리를 붙이면 웹을 검색한 뒤 상위 5개 결과의 URL을 자동으로 방문하여 각각 마크다운으로 변환해 돌려준다.
https://s.jina.ai/Who%20founded%20Jina%20AI
일반적인 웹 검색 API가 제목, URL, 짧은 설명만 반환하는 것과 달리, s.jina.ai는 검색 결과 페이지의 전체 본문까지 추출해준다는 점이 차별화 포인트다. 특정 도메인 내에서만 검색하려면 쿼리 파라미터에 site=jina.ai처럼 지정할 수도 있다.
검색 쿼리에 특수문자가 포함되어 있다면 반드시 URL 인코딩을 해야 한다. 공백은 %20, 물음표는 %3F로 치환한다. 인코딩하지 않으면 잘못된 검색 결과가 반환되거나 에러가 발생한다.
고급 기능 — 헤더로 제어하는 6가지 파워 옵션
Reader API의 진짜 힘은 HTTP 요청 헤더를 통한 세밀한 제어에 있다. 단순한 URL 변환을 넘어 구조화 데이터 추출, 불필요한 영역 제거, 토큰 예산 관리까지 가능하다.
ReaderLM-v2로 변환 품질 높이기
x-respond-with: readerlm-v2 헤더를 붙이면 Jina의 자체 소형 언어 모델인 ReaderLM-v2(1.5B 파라미터)가 HTML → 마크다운 변환을 처리한다. 이 모델은 29개 언어를 지원하며 최대 512K 토큰까지 처리할 수 있다. 구조가 복잡한 사이트에서 기본 파이프라인 대비 약 3배 높은 품질을 제공한다고 공식적으로 밝히고 있다. 다만 토큰 소모가 3배이므로 비용 대비 효과를 따져야 한다.
구조화 데이터 추출 (x-json-schema)
JSON 스키마를 헤더에 지정하면 페이지에서 해당 필드만 정확히 추출한다. 가격, 제목, 날짜 같은 특정 데이터만 깔끔하게 뽑아낼 수 있다. 자연어로 "가격이랑 제목만 뽑아줘"라고 쓸 수 있는 x-instruction 헤더도 활용 가능하다.
특정 요소 대기 (x-wait-for-selector)
CSS 셀렉터를 헤더에 넣으면 해당 요소가 렌더링될 때까지 기다린 다음 결과를 반환한다. JavaScript로 동적 로딩되는 콘텐츠를 잡을 때 유용하다. 예를 들어 x-wait-for-selector: #content로 지정하면 id가 content인 요소가 나타날 때까지 대기한다.
불필요한 영역 제거 (x-remove-selector)
헤더, 푸터, 사이드바 같은 특정 영역을 제외하고 싶을 때 x-remove-selector: nav, footer, .sidebar처럼 지정하면 된다. 반대로 특정 영역만 추출하고 싶다면 x-target-selector를 사용한다.
토큰 예산 설정 (x-token-budget)
최대 토큰 수를 지정하면 그 안에서 결과를 잘라준다. LLM 컨텍스트 윈도우가 넉넉하지 않을 때 편리하다. 예산을 초과하는 요청은 실패 처리된다.
iframe과 Shadow DOM 추출
웹 컴포넌트나 iframe 안에 숨어 있는 콘텐츠도 뽑아낼 수 있다. 각각 x-with-iframe: true와 x-with-shadow-dom: true 헤더로 활성화한다. 최신 웹앱에서 Shadow DOM을 적극 활용하는 추세를 고려하면 실무에서 꽤 중요한 기능이다.
| 헤더 옵션 | 기능 | 사용 예시 |
|---|---|---|
| x-respond-with: readerlm-v2 | 고품질 HTML→MD 변환 | 복잡한 구조의 사이트 |
| x-json-schema | 구조화 데이터 추출 | 가격, 제목 등 특정 필드 |
| x-wait-for-selector | 동적 요소 대기 | SPA, 지연 로딩 페이지 |
| x-remove-selector | 특정 영역 제거 | nav, footer, sidebar |
| x-token-budget | 토큰 상한 설정 | 컨텍스트 윈도우 제한 시 |
| x-with-generated-alt | 이미지 자동 캡셔닝 | 비전-언어 모델로 이미지 설명 생성 |
| x-no-cache | 캐시 우회 | 실시간 데이터 필요 시 |
| x-set-cookie | 쿠키 전달 | 로그인 필요 페이지 |
| x-proxy-url | 프록시 서버 사용 | 접근 제한 페이지 |
이미지 캡셔닝 기능(x-with-generated-alt: true)을 켜면 페이지 내 이미지를 비전-언어 모델로 분석하여 Image [idx]: [caption] 형태의 alt 태그를 자동 생성한다. 텍스트만 처리하는 다운스트림 LLM이 "이 페이지에 어떤 그림이 있었는지"까지 파악할 수 있게 된다. 다만 지연 시간이 늘어나므로 필요한 경우에만 켜는 것이 좋다.
비용 체계 — 무료부터 프리미엄까지
Reader API의 요금은 2025년 5월 6일에 개편된 통합 가격 모델을 따른다. 핵심은 기본 사용이 완전 무료라는 점이다.
무료 사용 (API 키 없음)
API 키 없이 브라우저나 curl로 바로 쓸 수 있다. 별도 가입이 필요 없고, IP 기반으로 분당 20건의 요청이 허용된다. 가볍게 테스트하거나 개인 프로젝트에 쓰기엔 충분하다.
무료 API 키 등록
Jina AI 사이트에서 API 키를 발급받으면(무료) 1,000만 토큰이 기본 제공된다. 레이트 리밋도 분당 100건, 분당 10만 토큰, 동시 요청 2건으로 올라간다. 비상업적 용도(CC-BY-NC 라이선스)로만 쓸 수 있다는 제한이 있다.
유료 플랜
무료 토큰을 소진하면 토큰 기반 과금으로 전환된다. 실패한 요청은 토큰이 차감되지 않는다.
| 플랜 | 비용 | 포함 토큰 | 레이트 리밋 (RPM / TPM / 동시) |
|---|---|---|---|
| Free (키 없음) | 0달러 | 없음 (IP 제한) | 20 RPM |
| Free (키 있음) | 0달러 | 1,000만 | 100 / 10만 / 2 |
| Prototype | 50달러 | 10억 | 500 / 200만 / 50 |
| Production | 500달러 | 1,100억 | 5,000 / 5,000만 / 500 |
100만 토큰당 단가로 환산하면 Prototype은 0.05달러, Production은 0.045달러다. ReaderLM-v2를 사용하면 토큰 소모가 3배로 늘어나는 점도 계산에 넣어야 한다.
2025년 5월 6일 이전에 자동 충전(auto-recharge)을 설정해둔 기존 사용자는 과거 가격이 유지된다. 이후에 신규 등록하거나 자동 충전 설정을 변경하면 새 가격이 적용되므로 기존 사용자는 설정 변경에 주의가 필요하다.
실전 활용 시나리오 4가지
Reader API가 실제로 빛을 발하는 구체적인 상황을 정리한다.
AI에게 웹 정보 먹이기
ChatGPT나 Claude에게 "이 기사 요약해줘"라고 할 때 URL을 r.jina.ai로 감싸서 결과를 복사-붙여넣기하면 끝이다. HTML을 통째로 넣는 것보다 훨씬 정확한 요약을 받을 수 있다. 토큰 소모도 대폭 줄어든다.
RAG 파이프라인 전처리
검색 증강 생성(RAG) 시스템에서 웹 데이터를 벡터 DB에 넣으려면 깨끗한 텍스트가 필수다. Reader API가 HTML 정제 단계를 대신 처리해주므로 별도의 전처리 코드를 작성할 필요가 없다. Elasticsearch, Qdrant 등 주요 벡터 DB와의 연동 튜토리얼도 공식 문서에 제공되고 있다.
AI 에이전트의 웹 탐색
자율 에이전트가 웹을 탐색하며 정보를 수집할 때 생 HTML을 파싱하는 건 복잡하고 불안정하다. r.jina.ai를 거치면 깨끗한 텍스트로 들어오니 에이전트가 훨씬 안정적으로 작동한다. LangChain, LlamaIndex 등 주요 프레임워크에 로더(Loader)로 통합되어 있다.
PDF 문서 처리
PDF URL을 그대로 넣으면 이미지가 많은 학술 논문, 다단 구조 문서에서도 텍스트를 추출하고 차트까지 설명해준다. curl https://r.jina.ai/https://example.com/paper.pdf -o result.md 한 줄로 논문을 마크다운 파일로 변환할 수 있다.
스트리밍 모드(Accept: text/event-stream 헤더)를 쓰면 대용량 페이지에서도 점진적으로 결과를 받을 수 있다. 일반 모드에서 결과가 불완전하게 나올 때 특히 유용하다. 마지막 청크가 가장 완전한 최종 결과를 담고 있으므로 LLM 텍스트 생성 스트리밍과는 다른 방식임을 유의해야 한다.
경쟁 도구 비교 — Firecrawl, Bright Data, Crawl4AI
웹 콘텐츠를 LLM 친화 포맷으로 바꿔주는 도구는 Reader API만 있는 게 아니다. 각 도구의 강점이 다르므로 용도에 맞게 선택해야 한다.
Firecrawl은 사이트 전체를 크롤링하는 데 강하다. 서브페이지까지 전부 긁어서 데이터로 만드는 방식이며 속도가 빠르다. 자체 FIRE-1 에이전트가 버튼 클릭, 페이지네이션, 간단한 CAPTCHA 해결까지 처리한다. 반면 r.jina.ai는 단일 페이지를 정밀하게 추출하는 쪽에 최적화되어 있다.
Bright Data는 산업용 웹 데이터 플랫폼이다. JavaScript가 무거운 사이트, 로그인이 필요한 사이트, 안티봇이 빡빡한 사이트를 뚫는 데 특화되어 있다. 글로벌 프록시 네트워크와 CAPTCHA 자동 해결 기능이 내장되어 있어 r.jina.ai가 접근하기 힘든 영역을 커버한다.
Crawl4AI는 오픈소스 크롤링 도구로 로컬에서 완전히 제어 가능한 점이 장점이다. 자체 서버에서 돌려야 하므로 인프라 관리 부담이 있지만, 비용이 발생하지 않고 데이터 프라이버시를 완전히 통제할 수 있다.
| 비교 항목 | r.jina.ai | Firecrawl | Bright Data |
|---|---|---|---|
| 핵심 강점 | 단일 페이지 정밀 추출 | 사이트 전체 크롤링 | 안티봇·프록시 특화 |
| JS 렌더링 | 헤드리스 Chrome | HTTP 또는 Chromium | 자체 브라우저 인프라 |
| 무료 사용 | API 키 없이 가능 | 500 페이지 | 체험판 제공 |
| 가격 단위 | 토큰 기반 | 페이지 크레딧 기반 | 요청·트래픽 기반 |
| 진입 가격 | 0달러 (무료) | 16달러/월 (3,000페이지) | 별도 문의 |
| 오픈소스 | Apache-2.0 | AGPL-3.0 | 비공개 |
| 검색 기능 | s.jina.ai 내장 | 없음 (별도 구현) | 없음 |
| AI 모델 내장 | ReaderLM-v2 (1.5B) | 마크다운 리덕션 | 없음 |
| SPA 처리 | Puppeteer 기반 | Chromium 기반 | 자체 렌더링 |
| 이미지 캡셔닝 | VLM 자동 캡셔닝 | 미지원 | 미지원 |
정리하면 이렇다. 사이트 전체를 통째로 긁고 싶으면 Firecrawl, 한 페이지를 깔끔하게 AI용으로 변환하고 싶으면 r.jina.ai, 접근이 까다로운 사이트를 뚫어야 하면 Bright Data가 적합하다.
r.jina.ai는 robots.txt를 확인하는 옵션(x-robots-tag)을 제공하지만 기본값은 비활성이다. 상용 서비스에서 대량 크롤링을 할 때는 반드시 대상 사이트의 이용약관과 robots.txt를 확인해야 한다. 법적 리스크는 도구가 아닌 사용자의 책임이다.
기술 구조와 내부 동작 원리
Reader API가 URL을 받아 마크다운을 뱉어내기까지 내부에서 일어나는 일은 생각보다 복잡하다.
첫 단계는 브라우저 렌더링이다. Puppeteer와 헤드리스 Chrome을 사용하여 대상 URL을 실제 브라우저처럼 로딩한다. JavaScript로 동적 렌더링되는 SPA도 이 단계에서 처리된다. x-wait-for-selector나 x-timeout 헤더로 렌더링 완료 시점을 세밀하게 제어할 수 있다.
두 번째는 콘텐츠 추출이다. Readability 알고리즘(Mozilla에서 개발한 것과 유사)을 적용하여 본문 영역을 식별하고 광고, 네비게이션, 푸터 등의 노이즈를 걷어낸다. x-target-selector와 x-remove-selector로 이 과정을 수동 보정할 수 있다.
세 번째는 마크다운 변환이다. Turndown 라이브러리 기반으로 HTML을 마크다운으로 변환한다. 헤딩 스타일, 리스트 마커, 링크 포맷 등을 헤더로 커스터마이징할 수 있다. ReaderLM-v2를 활성화하면 이 단계에서 1.5B 파라미터 언어 모델이 개입하여 더 정교한 변환을 수행한다.
마지막으로 후처리다. 이미지 캡셔닝(VLM 기반), 링크 요약, 토큰 예산 적용 등이 이 단계에서 처리된다. 캐시는 기본 3,600초 동안 유지되며 x-no-cache로 우회 가능하다.
이 전체 파이프라인이 Jina AI의 클라우드에서 돌아가므로 사용자는 브라우저 관리, 프록시 설정, 렌더링 대기 같은 인프라 문제를 신경 쓸 필요가 없다. GitHub에 공개된 코드가 실제 r.jina.ai 프로덕션 서버에 배포되는 단일 코드베이스라는 점도 투명성 면에서 주목할 만하다.
| 처리 단계 | 핵심 기술 | 제어 헤더 |
|---|---|---|
| 브라우저 렌더링 | Puppeteer + 헤드리스 Chrome | x-timeout, x-wait-for-selector |
| 콘텐츠 추출 | Readability 알고리즘 | x-target-selector, x-remove-selector |
| 마크다운 변환 | Turndown / ReaderLM-v2 | x-respond-with |
| 후처리 | VLM 이미지 캡셔닝 | x-with-generated-alt, x-token-budget |
도입 시 주의사항과 한계
어떤 도구든 만능은 아니다. Reader API를 실전에 투입하기 전에 알아야 할 한계점과 주의사항을 정리한다.
첫째, 로그인이 필요한 페이지는 기본적으로 접근할 수 없다. x-set-cookie 헤더로 쿠키를 전달하면 일부 해결되지만, 복잡한 인증 흐름이 필요한 사이트는 Bright Data 같은 전문 도구가 더 적합하다.
둘째, 안티봇 보호가 강력한 사이트에서는 차단당할 수 있다. Cloudflare 등의 보호 메커니즘 앞에서는 프록시 서버(x-proxy-url)를 활용하거나 국가별 프록시(x-proxy-country) 설정을 시도해볼 수 있지만 보장되지는 않는다.
셋째, 평균 응답 지연 시간이 약 7.9초로 보고되고 있다. 실시간 응답이 필요한 서비스에는 적합하지 않을 수 있다. 스트리밍 모드를 활용하거나 캐시를 적극적으로 활용하여 체감 지연을 줄이는 전략이 필요하다.
넷째, 무료 티어의 비상업적 용도 제한(CC-BY-NC)을 간과하기 쉽다. 상용 서비스에 Reader API를 통합하려면 반드시 유료 플랜(Prototype 50달러 또는 Production 500달러)으로 전환해야 한다.
지금까지 다룬 내용을 종합하면 Reader API는 "한 페이지를 AI에게 먹이기 위해 변환하는" 특정 작업에서 압도적인 편의성을 제공하는 도구다. URL 앞에 한 줄만 붙이면 되는 진입 장벽의 부재, PDF와 이미지 캡셔닝까지 지원하는 확장성, 그리고 무료부터 시작할 수 있는 가격 구조가 핵심 경쟁력이다.
당장 AI에게 웹 정보를 넘겨야 하는 상황이라면 브라우저 주소창에 https://r.jina.ai/를 붙여보는 것부터 시작하면 된다. 가입도 결제도 없이 30초 안에 결과를 확인할 수 있다. 그 후 워크플로우에 맞게 curl이나 Python으로 확장하고, 고급 헤더 옵션으로 세밀하게 튜닝해 나가면 된다.