빠른 시작
curl -X GET "https://보수아카이브.com/api/v1/search?q=윤석열" \ -H "X-API-Key: bsu_your_api_key_here"
API 키는 API 키 관리 페이지에서 발급받을 수 있습니다.
인증
모든 API 요청에는 X-API-Key 헤더가 필요합니다.
// JavaScript fetch 예시
const response = await fetch('https://보수아카이브.com/api/v1/search?q=검색어', {
headers: {
'X-API-Key': 'bsu_your_api_key_here'
}
});
const data = await response.json();엔드포인트
GET
/api/v1/search쿼리 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
q | string | 예 | 검색 쿼리 (최대 200자) |
limit | number | 아니오 | 결과 수 (기본: 10, 최대: 50) |
grouped | boolean | 아니오 | 영상별 그룹화 (기본: true) |
응답 형식
그룹화된 응답 (grouped=true)
{
"query": "윤석열",
"videoGroups": [
{
"videoId": "abc123",
"youtubeId": "dQw4w9WgXcQ",
"title": "영상 제목",
"publishedAt": "2024-01-15T00:00:00.000Z",
"channel": { "id": "ch1", "title": "채널명" },
"clips": [
{
"id": "clip1",
"content": "클립 내용...",
"startSec": 120,
"endSec": 150,
"similarity": 0.85
}
],
"relevanceScore": 0.85
}
],
"meta": {
"totalClips": 5,
"totalVideos": 2,
"queryTime": 234,
"tier": "FREE",
"rateLimit": 100
}
}플랫 응답 (grouped=false)
{
"query": "윤석열",
"clips": [
{
"id": "clip1",
"content": "클립 내용...",
"startSec": 120,
"endSec": 150,
"similarity": 0.85,
"video": {
"youtubeId": "dQw4w9WgXcQ",
"title": "영상 제목",
"publishedAt": "2024-01-15T00:00:00.000Z",
"channel": { "title": "채널명" }
}
}
],
"meta": { ... }
}요청 제한 (Rate Limiting)
| 티어 | 일일 요청 수 | 설명 |
|---|---|---|
| FREE | 100 | 기본 무료 티어 |
| BASIC | 1,000 | 소규모 프로젝트 |
| PRO | 10,000 | 대규모 서비스 |
| UNLIMITED | 무제한 | 파트너 전용 |
요청 제한은 매일 자정(KST)에 리셋됩니다.
에러 응답
| 상태 코드 | 에러 | 설명 |
|---|---|---|
400 | Query parameter "q" is required | 검색어 누락 |
401 | API key required | API 키 헤더 누락 |
401 | Daily rate limit exceeded | 일일 요청 제한 초과 |
500 | Search failed | 서버 오류 |
CORS
API는 모든 도메인에서 호출 가능합니다 (Access-Control-Allow-Origin: *). 브라우저에서 직접 호출할 수 있습니다.