Search Engine API

개요

Tavily 호환 AI 검색 엔진 API입니다. API 키 없이도 작동하며, Naver + Bing + Wikipedia + GitHub 등 10+ 다중 백엔드를 병렬로 검색합니다. 한국어 검색에 최적화되어 있으며, 딥 리서치, 채팅, 이미지/뉴스/비디오 검색, OpenAI 호환 API 등 다양한 기능을 제공합니다.

20+

API 엔드포인트

API 키 필요

∞

검색 한도

10+

검색 백엔드

POST /api/search

웹 검색을 수행하고 구조화된 결과를 반환합니다. Tavily Search API와 호환됩니다.

요청 본문 (JSON)

파라미터	타입	기본값	설명
query	string	-	필수. 검색어
search_depth	"basic" \| "advanced"	"basic"	검색 깊이
topic	"general" \| "news" \| "finance"	"general"	검색 주제
max_results	number	10	결과 수 (1-20)
include_answer	boolean	false	AI 답변 포함
include_raw_content	boolean	false	전체 콘텐츠 포함
include_domains	string[]	[]	포함할 도메인
exclude_domains	string[]	[]	제외할 도메인
time_range	"day"\|"week"\|"month"\|"year"\|"any"	"any"	시간 범위
sort_by	"relevance" \| "date"	관련성+신선도 블렌드	정렬 기준. 기본값은 관련성 70% + 최신성 30% 블렌드로 최신 데이터를 상위에 노출
max_tokens	number	4000	결과당 최대 토큰

Focus Mode (선택)

검색 영역을 전문화하여 더 정확한 결과를 얻습니다.

모드	설명	사용처
all	모든 백엔드 (기본값)	일반 검색
academic	Wikipedia + arXiv + 학술 소스 우선	논문, 연구, 학술 자료
news	Bing News + HN + Reddit 최신 뉴스	속보, 트렌드
writing	웹 전체 콘텐츠, 영감 위주	글쓰기, 아이디어 발굴
video	YouTube + 튜토리얼 중심	동영상 강좌, 가이드
social	Reddit + HackerNews 커뮤니티	커뮤니티 의견, 토론
finance	주식/재무 데이터 집중	주가, 실적, 재무 분석
math	Wikipedia + 웹 수식/정리 검색	수학, 과학 공식

focus 파라미터로 지정 (POST JSON 또는 GET 쿼리 파라미터). 예: {"focus": "academic"} 또는 ?focus=academic

예시 요청

curl -X POST https://YOUR_DOMAIN/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Cloudflare Workers AI",
    "max_results": 5,
    "include_answer": true,
    "search_depth": "advanced"
  }'

예시 응답

{
  "query": "Cloudflare Workers AI",
  "answer": {
    "text": "Cloudflare Workers AI is...",
    "confidence": 0.85,
    "sources": [0, 1, 2]
  },
  "results": [
    {
      "title": "Cloudflare Workers AI",
      "url": "https://developers.cloudflare.com/workers-ai/",
      "content": "Clean snippet text...",
      "score": 0.92,
      "domain": "developers.cloudflare.com",
      "published_date": "2026-01-15T00:00:00.000Z"
    }
  ],
  "response_time_ms": 3200,
  "backend": "naver+bing+wikipedia",
  "fallback_used": false,
  "related_queries": ["Cloudflare Workers AI guide", ...]
}

GET /api/search

간단한 GET 요청으로 검색할 수 있습니다 (에이전트 친화적).

GET /api/search?query=Cloudflare+Workers&max_results=5&include_answer=true

# 또는 짧은 형태
GET /api/search?q=AI+agents&limit=10

POST /api/extract

URL에서 깨끗한 콘텐츠를 추출합니다. Jina Reader + HTMLRewriter 폴백.

curl -X POST https://YOUR_DOMAIN/api/extract \
  -H "Content-Type: application/json" \
  -d '{
    "urls": "https://example.com/article",
    "include_images": false,
    "max_tokens": 8000
  }'

# 여러 URL
curl -X POST https://YOUR_DOMAIN/api/extract \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://a.com", "https://b.com"] }'

# GET 방식
GET /api/extract?urls=https://a.com,https://b.com

GET/POST /api/images

이미지 검색. 크기/색상/타입 필터 지원.

GET /api/images?query=cat&size=medium&color=color&type=photo

GET/POST /api/news

뉴스 검색. 소스 필터(all/bing/hackernews/reddit) 및 트렌딩 지원.

GET /api/news?query=AI&source=all
GET /api/news/trending

POST /api/research

멀티스텝 딥 리서치. 복잡한 쿼리를 하위 쿼리로 분해하여 종합적인 답변을 생성합니다.

POST /api/research
{
  "query": "양자 컴퓨팅의 현재와 미래",
  "depth": "quick",
  "max_sources": 15
}

GET /api/suggest

검색어 자동완성 제안 (DuckDuckGo → Bing 폴백).

GET /api/suggest?q=quantum

POST /api/chat

멀티턴 대화형 채팅. 컨텍스트를 유지하며 연구를 수행합니다.

POST /api/chat
{
  "query": "양자 컴퓨팅의 응용 분야는?",
  "thread_id": "...", // 생략 시 새 스레드
  "depth": "quick",
  "max_sources": 15
}

POST /api/council

여러 AI 모델의 응답을 비교합니다 (Workers AI, OpenAI, Anthropic).

POST /api/council
{
  "query": "Explain quantum computing",
  "models": ["@cf/meta/llama-3.1-8b", "gpt-4o-mini"]
}

GET/POST/PUT/DELETE /api/pages

연구 보고서를 저장하고 공유합니다.

POST /api/pages  # 저장
GET /api/pages   # 목록 조회
GET /api/pages/:id  # 상세 조회
PUT /api/pages/:id  # 수정
DELETE /api/pages/:id  # 삭제

POST /api/upload

파일 업로드 (TXT/MD/PDF) 및 AI 요약 분석.

GET/POST /api/products

Product Hunt + G2에서 소프트웨어 제품과 리뷰를 검색합니다.

GET /api/products?query=AI+code+generator
POST /api/products
{
  "query": "project management",
  "max_results": 5
}

GET/POST /api/video

YouTube 비디오 검색. 트랜스크립트 추출 및 URL 기반 상세 콘텐츠 추출 지원.

# 비디오 검색 (트랜스크립트 포함)
GET /api/video/search?query=React+tutorial&include_transcripts=true
POST /api/video/search
{
  "query": "machine learning course",
  "max_results": 3,
  "include_transcripts": true
}

# URL → 상세 콘텐츠 추출 (제목/설명/키워드/채널/조회수/좋아요/게시일 + 선택적 트랜스크립트)
GET /api/video/details?url=https://youtu.be/abcXYZ&include_transcript=true&lang=ko
GET /api/video/details?video_id=abcXYZ&include_transcript=true

# 트랜스크립트 조회 (json | text | srt)
GET /api/video/transcript?video_id=abcXYZ&format=text

GET/POST/PUT/DELETE /api/spaces

워크스페이스 관리. 파일, 시스템 인스트럭션, 검색 컨텍스트 설정.

POST /api/spaces
{
  "name": "My Research Project",
  "description": "Project about quantum computing",
  "instructions": "Focus on academic sources",
  "focus_mode": "academic"
}

GET /api/canary

Parser 회귀 감지. 각 백엔드에 실제 검색을 실행하여 결과 추출 정상 여부를 확인합니다. HEALTH_CANARY_ENABLED=true 필요.

GET /api/suggest

검색어 자동완성 제안 (DuckDuckGo → Bing 폴백).

GET /api/suggest?q=quantum

POST /v1/chat/completions

OpenAI 호환 엔드포인트. 기존 OpenAI SDK/라이브러리로 검색 엔진을 호출할 수 있습니다.

모델	설명
search-engine	기본 웹 검색 + AI 답변
search-engine-deep	고급 검색 (더 깊은 분석)
research-engine	멀티스텝 딥 리서치

curl -X POST https://YOUR_DOMAIN/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "search-engine",
    "messages": [
      {"role": "user", "content": "최신 AI 뉴스 알려줘"}
    ],
    "max_tokens": 2000
  }'

# 모델 목록 조회
GET /v1/models

GET/POST/DELETE /api/keys

API 키 관리. 키 생성, 조회, 폐기. API_KEY_DO 바인딩 필요.

GET /api/monitor

SLO 모니터 리포트. 에러 예산, 캐시 적중률, 알림 평가.

GET /api/usage

사용량 통계: 요청 수, 오류율, 서브리퀘스트 수.

Hermes Agent 연동

Hermes Agent가 이 API를 사용하여 제한 없이 인터넷을 검색할 수 있습니다.

Python (requests)

import requests

BASE_URL = "https://YOUR_DOMAIN"

# 검색
response = requests.post(f"{BASE_URL}/api/search", json={
    "query": "latest AI news",
    "max_results": 10,
    "include_answer": True,
    "search_depth": "advanced"
})
data = response.json()

# AI 답변 출력
if data.get("answer"):
    print("Answer:", data["answer"]["text"])

# 검색 결과 출력
for r in data["results"]:
    print(f"[{r['score']:.2f}] {r['title']} - {r['url']}")
    print(f"  {r['content'][:200]}...")

JavaScript (fetch)

const BASE_URL = "https://YOUR_DOMAIN";

// Search
const res = await fetch(`${BASE_URL}/api/search`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "latest AI news",
    max_results: 10,
    include_answer: true
  })
});
const data = await res.json();

// Extract content from URL
const ext = await fetch(`${BASE_URL}/api/extract`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ urls: "https://example.com/article" })
});
const extData = await ext.json();

OpenAI Function Calling (Tool Definition)

{
  "type": "function",
  "function": {
    "name": "web_search",
    "description": "Search the internet for current information",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "The search query" },
        "max_results": { "type": "number", "default": 10 },
        "include_answer": { "type": "boolean", "default": true },
        "search_depth": { "type": "string", "enum": ["basic", "advanced"], "default": "basic" },
        "topic": { "type": "string", "enum": ["general", "news", "finance"], "default": "general" }
      },
      "required": ["query"]
    }
  }
}

아키텍처

검색 백엔드: Naver (한국어 주력) + Bing (다국어) + Wikipedia + GitHub + HN + Reddit + arXiv 병렬 검색 - API 키 불필요

콘텐츠 추출: Jina AI Reader (r.jina.ai) → Cloudflare HTMLRewriter (폴백)

AI 답변: Cloudflare Workers AI (Llama 3.1) → 추출적 요약 (폴백, AI 불필요)

배포: Cloudflare Pages (엣지 글로벌 배포, 300+ 위치)

API 문서

개요