콘텐츠 API

편집진과 AI 가 함께 만들고 검증 절차를 거친 콘텐츠를 JSON, Markdown, TXT, HTML, JSON-LD 포맷과 다국어로 제공하는 API 입니다. 같은 키로 시맨틱 검색과 콘텐츠 음성(TTS) 메타, 그리고 모델 학습·RAG 색인용 데이터셋(본문 코퍼스·instruction·다국어 병렬)까지 이용할 수 있고, 임베딩 벡터 원본과 음성 mp3 는 Pro 플랜에서 제공합니다. 무료 키를 발급받아 바로 시작할 수 있습니다.

요금제

API 테스트

사용법

발급받은 키를 Authorization 헤더에 넣어 호출합니다. 아래는 엔드포인트·파라미터·응답 포맷과 예시입니다.

엔드포인트

데이터셋 (학습·RAG)

모델 학습·파인튜닝·RAG 색인처럼 여러 건을 한 번에 가져가야 하는 용도를 위해, 콘텐츠를 학습용 스키마로 정규화해 제공합니다. 목록·단건 API 와 동일하게 page·per_page·category·tag·updated_since 를 지원하고, format=jsonl 로 받으면 학습 파이프라인에 바로 넣을 수 있습니다.

per_page 상한은 Free 플랜 10건, Pro 플랜은 종류별로 최대 100건입니다(임베딩은 20건). 크레딧은 요청한 per_page 기준으로 계산되어, 같은 분량을 단건 조회로 반복하는 것보다 적게 듭니다.

데이터셋 API 는 무료 데이터 제공을 대체하지 않습니다. 콘텐츠 낱건을 TXT·Markdown·JSON·JSON-LD 로 가져가는 무인증 경로는 지금처럼 무료로 계속 제공됩니다. 무료 데이터 이용 안내

제공 언어

• 1티어 - 번역 검수를 마친 언어입니다. 사람이 읽는 웹 페이지·검색 노출(sitemap·hreflang)·AI 음성(TTS)·임베딩까지 전부 제공됩니다.
• 2티어 - 기계번역 데이터 전용 언어입니다. 데이터 파일과 API 로만 제공되며 웹 페이지·검색 노출·음성(TTS)·임베딩은 제공되지 않습니다. 검수 전이라는 뜻으로 translation_status: machine 라벨이 항상 함께 표기됩니다.

API 의 lang 파라미터에는 위 설정값을 그대로 넣습니다. 콘텐츠 단건·데이터셋은 2티어 언어도 받지만, 음성(TTS)·임베딩 엔드포인트는 1티어 언어만 응답합니다.

쿼리 파라미터

지원 포맷 (단건 조회 format)

예시

인증은 Authorization: Bearer 헤더 또는 X-Api-Key 헤더를 사용합니다.

# 목록 조회
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents?lang=ko&page=1&per_page=20"

# 카테고리로 필터
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents?lang=ko&category=<CATEGORY_SLUG>"

# 태그로 필터
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents?lang=ko&tag=<TAG_SLUG>"

# 증분 동기화 (특정 시각 이후 수정분)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents?updated_since=2026-01-01T00:00:00Z"

# 특정 서비스만 (선택 - 안 주면 전체)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents?lang=ko&service=<SERVICE>"

# 단건 조회 (HTML 포맷)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents/<CONTENT_ID>?lang=ko&format=html"

# slug 로 단건 조회 (Markdown 포맷)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents/by-slug/<SLUG>?lang=ko&format=md"

# 이미지 메타데이터
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents/<CONTENT_ID>/images"

# 카테고리 목록
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/categories?lang=ko"

# 태그 목록
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/tags?lang=ko"

# 바인더 목록
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/binders?lang=ko"

# 바인더 소속 콘텐츠
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/binders/<BINDER_SLUG>/contents?lang=ko"

# 사이트 목록
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/sites?lang=ko"

# 사이트 소속 콘텐츠
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/sites/<SITE_SLUG>/contents?lang=ko"

# 검색
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/search?q=<KEYWORD>&lang=ko"

# 시맨틱 검색 (벡터 의미 검색)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/search?q=<KEYWORD>&mode=semantic&lang=ko"

# 임베딩 벡터 원본 (Pro)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents/<CONTENT_ID>/embeddings?lang=ko"

# TTS 음성 메타
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents/<CONTENT_ID>/audio?lang=ko"

# TTS 음성 mp3 (Pro)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/contents/<CONTENT_ID>/audio/ko"

# 데이터셋 카탈로그
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets"

# 본문 코퍼스 (한 번에 여러 건)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets/corpus?lang=ko&per_page=100"

# 본문 코퍼스 JSONL (학습 파이프라인용)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets/corpus?lang=ko&format=jsonl"

# 증분 동기화 (특정 시각 이후 수정분만)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets/corpus?updated_since=2026-01-01T00:00:00Z&format=jsonl"

# instruction 데이터셋 (FAQ → messages 쌍)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets/qa?lang=ko&format=jsonl"

# 다국어 병렬 코퍼스 (검수본만)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets/parallel?langs=ko,en,ja&status=reviewed"

# 임베딩 벡터 벌크 (Pro)
curl -H "Authorization: Bearer <API_KEY>" \
  "https://onbinder.com/api/v1/datasets/embeddings?lang=ko&per_page=20"

선택: 헤더 대신 쿼리 토큰(URL 인증)을 쓸 수 있습니다. "내 콘텐츠 API" 페이지에서 발급한 QUERY_KEY 를 붙여 헤더 없이 호출합니다. URL·로그에 노출될 수 있어 읽기 전용·만료·폐기 가능하며, 민감하지 않은 편의용으로만 권장합니다.

https://onbinder.com/api/v1/contents?query_key=<QUERY_KEY>&lang=ko

월 쿼터는 성공(2xx) 응답만 산입되며, 잔여량은 X-Monthly-Quota-* 응답 헤더로 확인할 수 있습니다. 쿼터는 매월 1일(KST)에 초기화됩니다.

시맨틱 검색·임베딩·오디오·데이터셋 요청은 크레딧을 더 사용합니다: 시맨틱 검색(mode=semantic) 2배, 임베딩 벡터 원본 5배, TTS 음성 mp3 파일 3배(메타는 1배). 데이터셋은 요청한 per_page 에 비례합니다(코퍼스·QA 는 10건당 1, 병렬은 5건당 1, 임베딩은 2건당 1). 벡터 원본·음성 mp3 파일·임베딩 데이터셋은 Pro 플랜 전용이며, 각 기능은 관리자가 해당 API(임베딩/오디오/데이터셋)를 활성화한 경우에만 동작합니다.

API 이용에는 다음 정책이 적용됩니다: 이용약관 · 환불정책 · 개인정보처리방침