Ctrlk
App StoreGoogle PlayWeb
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Page 1

NewsCover Library (외부 공개 문서 초안, 한글판 v6)

GitBook(docs.ns3.ai/newscover-library) 교체용 초안. 한글 확정 후 영어로 번역 예정.

1. 개요 (Overview)

NewsCover Library("NewsCover")는 뉴스에 어울리는 커버 이미지를 제공하는 서비스입니다. 키워드 또는 헤드라인을 입력하면 라이브러리에서 매칭되는 커버를 즉시 반환합니다. 라이브러리는 현재 약 3,000개 엔티티와 10,000장의 커버를 보유하며, 다음 카테고리로 구성됩니다.

카테고리
예시

암호화폐

Bitcoin, Ethereum, Solana

기업 및 브랜드

Tesla, Apple, Binance

국가

United States, Japan, South Korea

통화

Dollar, Yen, Euro

원자재

Gold, Oil, Copper

인물

주요 정치인 · CEO · 투자자

기관 · 지수 · 규제 · 개념

Fed, SEC, S&P 500, CPI

기타

그 외 크립토 · 경제 뉴스 빈출 엔티티

CMC 500, Nasdaq 100, S&P 500의 전 구성 종목을 커버하며, 주요 글로벌 브랜드와 크립토·경제 뉴스에 자주 등장하는 엔티티 대부분을 포함합니다.

정밀성을 위한 설계. 매칭 엔진은 잘못된 커버 사용을 최소화하도록 설계되었습니다: 잘못된 커버보다 커버가 없는 것이 낫다. 엔진은 실제 뉴스 헤드라인 5,000건을 시뮬레이션해 과매칭·충돌 검사를 수행하고 그에 맞춰 고도화되었습니다.

규격화된 커버와 그리드 시스템. 커버 이미지에 요구되는 조건은 플랫폼과 뉴스에 따라 다릅니다. 커버가 1장 쓰일 수도, 2장이 나란히 쓰일 수도 있고, 주요 비율과 플랫폼에서 피사체가 올바르게 표시되어야 하며, 두 커버가 한 공간에 함께 렌더링될 때는 시각적 이질감이 최소화되어야 합니다. 이 요구사항을 충족하기 위해 모든 커버는 그리드 시스템(인물·심볼·워드마크·사물 레이아웃)으로 규격화된 고품질 이미지로 제작되며, 그리드 검사를 통과하고 최종적으로 사람의 검수를 거친 뒤에만 배포됩니다.

두 가지 사용 방법 (웹 및 API):

모드
보내는 것
적합한 경우

헤드라인 검색 headline=

헤드라인 원문 그대로

자동화·AI 재작성 파이프라인 (키워드 추출 불필요)

키워드 검색 q=

직접 선정한 키워드 (콤마 구분, 최대 4개)

에디터가 의도한 대로 커버를 구성할 때

두 모드는 같은 엔드포인트에서 쿼리 파라미터만 다르며, 동일한 응답 스키마(7장)를 공유합니다. 인증·rate limit 없음, CORS 허용(Access-Control-Allow-Origin: *)으로 서버는 물론 브라우저 프론트엔드에서도 직접 호출할 수 있습니다.

  • 헤드라인 검색: GET https://api.ns3.ai/newscover?headline={헤드라인 텍스트}

  • 키워드 검색: GET https://api.ns3.ai/newscover?q={키워드1,키워드2,...}

커버 비율과 대표 매체

비율
형태
대표 매체/용도

1.75:1 (원본, 1750×1000)

단일 · 분할

X(트위터) 타임라인 이미지

1:1

단일

정방형 썸네일 · 앱 내 카드

1.91:1

단일 · 분할

OG 이미지 (소셜 링크 프리뷰), 웹 표준 1200×630

2.5:1

단일 · 분할

와이드 뉴스 피드 배너

분할(Split)형은 두 엔티티의 커버를 한 커버 안에 2패널로 나란히 배치하는 구성입니다(X/트위터에서 널리 쓰이는 스타일). 모든 커버는 그리드 검사를 통과했기 때문에, 단일형은 물론 분할 배치에서도 피사체가 올바르게 표시되고 두 커버 간 시각적 이질감이 없습니다.

2. 검색 모드 선택 가이드: headline= vs q=

headline= 헤드라인 검색

q= 키워드 검색

입력

헤드라인/속보 문장 그대로

직접 추출한 키워드 (콤마 구분)

엔티티 추출 주체

NewsCover 라이브러리 (자동)

에디터 (직접)

매칭

엄격: 오매칭 최소화

느슨: 발견성 우선

에디터 작업량

없음: 원문만 전달

핵심 키워드 선정 필요

적합

자동화, AI 재작성 피드

사람 편집, 키워드가 명확한 경우

헤드라인 검색은 준비된 헤드라인에서 커버를 바로 도출하며, 별도 워크플로우가 필요 없습니다. 낮은 확률로 무매칭·오매칭이 발생할 수 있으므로, 독자에게 완결된 결과를 보장하려면 최종 단계에서 사람의 검수를 권장합니다.

키워드 검색은 에디터가 선택한 엔티티만 도출하므로, 커버가 의도한 대로 정확히 구성됩니다.

헤드라인 검색의 정밀함은 구조적입니다. 헤드라인 텍스트는 통제할 수 없으므로, 키워드 검색보다 엄격한 매칭이 적용됩니다:

  • 티커는 대소문자를 구분하고, 이름은 구분하지 않습니다. "Bitcoin trades near record highs" 속 소문자 near는 그냥 단어 "near"이므로 아무것도 반환하지 않고, 대문자 NEAR는 NEAR 티커에 매칭됩니다. Apple이나 apple은 이름이므로 어느 쪽이든 회사에 매칭됩니다. (※ 따라서 헤드라인은 대소문자를 바꾸지 말고 원문 그대로 보내세요.)

  • 엣지케이스 처리가 내장되어 있습니다. 수천 건의 실제 헤드라인 시뮬레이션으로 도출한 오매칭 패턴이 엔진과 키워드 사전에 반영되어 있습니다. 예를 들어 금액 단위로 쓰인 통화("Raises Funding Worth 100 Million Yuan")는 커버를 트리거하지 않습니다.

q= 모드는 의도적으로 느슨합니다: 키워드를 직접 골라 보낸 것이므로 소문자 near를 입력해도 NEAR 커버를 반환합니다.

요약: 기계(또는 AI 재작성기)가 피드를 만든다면 headline=, 사람이 키워드를 고른다면 어느 쪽이든 좋습니다.

3. 키워드 검색 가이드

표기가 조금 달라도 같은 엔티티로 인식합니다. 대소문자, 공백, 하이픈, 특수문자 차이는 매칭에 영향을 주지 않습니다:

입력
매칭

Polymarket / poly market / poly-market / POLY_MARKET

Polymarket

$BTC / btc

BTC

Bank of England / bankofengland

Bank of England

높은 매칭률을 위한 팁

  • 고유 엔티티명 또는 티커를 사용하세요: Bitcoin, BTC, Tesla, Fed, Japan

  • 일반 명사·서술구는 매칭되지 않습니다: crypto market crash, price surge

  • 키워드는 영어만 지원합니다

매칭이 없을 때: 웹은 "No results found."를 표시하고, API는 모드별 무매칭 응답을 반환합니다(5·6장 참조).

4. NewsCover Web (에디터용)

URL: https://ns3.ai/newscover

  1. 검색창에 키워드를 입력합니다 (영어)

  2. 매칭된 키워드 그룹의 모든 이미지가 표시됩니다

  3. 이미지별 비율 프리뷰를 확인합니다: 1:1 정방형 / 1.75:1 단일·분할 / 1.91:1 단일·분할 / 2.5:1 단일·분할 / 원본 비율

  4. Download Image 버튼으로 저장하거나, URL 복사 아이콘으로 이미지 주소를 복사합니다

분할(Split) 프리뷰는 X(트위터) 등에서 널리 쓰이는 2패널 분할 커버 스타일입니다.

5. 헤드라인 검색 API: headline=

헤드라인 원문을 보내면, 엔진이 엔티티를 추출해 엔티티별 커버를 반환합니다.

동작 방식

  • 텍스트는 URL 인코딩해 보냅니다 (공백은 %20 또는 +). 브라우저·HTTP 라이브러리는 자동 처리합니다.

  • 헤드라인 텍스트의 앞 250자가 매칭 대상입니다. (250자 이상 입력해도 문제 없으나 250자 이후 엔티티는 매칭대상 아님)

  • 최대 5개 엔티티가 헤드라인 등장 순서대로 반환됩니다. 첫 번째 엔티티가 대표 주제일 확률이 높으므로, 단일 대표 커버가 필요하면 첫 번째를 사용하세요.

  • 최대 3단어 엔티티명까지 매칭됩니다("Bank of England", "Ki Young Ju"). 구두점은 자연스럽게 처리됩니다: "Bitcoin (BTC)", "BTC,", "Trump's" 모두 해당 엔티티에 매칭됩니다. 같은 헤드라인의 이름과 티커는 하나의 결과로 병합됩니다.

  • images는 배열입니다. 기본 모드에서는 매칭된 엔티티 그룹당 랜덤 커버 1장이 담깁니다: 같은 헤드라인은 항상 같은 엔티티를 반환하지만, 배정되는 커버 이미지는 호출마다 다를 수 있습니다.

  • **mode=extended**를 붙이면 각 엔티티 그룹이 보유한 모든 커버가 images 배열에 담겨 반환됩니다. 웹 검색과 동일한 결과를 API로 받는 것으로, 반환된 모든 이미지 중에서 에디터가 직접 골라 쓸 수 있습니다.

  • 매칭이 없으면 results는 빈 배열입니다. 아래 무매칭 예시를 참조하세요.

응답 예시: 엔티티 2개 매칭

GET https://api.ns3.ai/newscover?headline=Bitcoin surges as SEC approves ETF

input은 헤드라인에서 발견된 엔티티 표기를 그대로 돌려줍니다. 어떤 엔티티가 매칭됐는지는 name과 groupId로 식별하세요. groupId는 여러 기사에 걸쳐 같은 엔티티 커버가 반복되는지 확인하는 데도 쓸 수 있습니다.

응답 예시: 무매칭

GET https://api.ns3.ai/newscover?headline=The weather is nice today

매칭된 엔티티가 없으면 배열이 비어 있습니다. (q=는 키워드별로 matched: false 항목을 명시적으로 반환하는 것과 다릅니다. 6장 참조.) 이 경우를 위한 자체 폴백 커버를 준비하세요.

6. 키워드 검색 API: q=

직접 추출한 키워드를 보냅니다.

쿼리 규칙

  • 최대 4개 키워드, 콤마로 구분. 5개 이상이면 HTTP 400.

  • 키워드는 URL 인코딩하세요: 공백은 %20/+, &는 %26. 인코딩 안 된 공백은 요청이 실패하고, 인코딩 안 된 &는 쿼리가 조용히 잘립니다. (팁: bankofengland처럼 공백 없는 형태로 보내면 인코딩 문제를 원천 회피합니다. q=에서 대소문자는 무시됩니다.)

  • images는 배열이며, 기본 모드에서는 랜덤 커버 1장이 담깁니다. 같은 키워드라도 호출마다 다른 이미지가 나올 수 있습니다.

  • **mode=extended**를 붙이면 각 엔티티 그룹이 보유한 모든 커버가 images 배열에 담겨 반환됩니다.

동일 엔티티 병합 & 백업 키워드. 같은 엔티티로 귀결되는 키워드들은 하나의 결과로 병합되므로, 응답 항목 수가 보낸 키워드 수보다 적을 수 있습니다: 항상 input으로 매핑하세요. 이를 활용한 백업 키워드 패턴: 한 엔티티의 여러 표기를 함께 보내면(예: ?q=SamBankmanFried,BankmanFried,SBF) 등록된 표기가 매칭되고, 결과는 하나만 반환되며, 같은 주제가 중복될 위험이 없습니다.

응답 예시: 단일 키워드

GET https://api.ns3.ai/newscover?q=bitcoin

results는 키워드가 1개여도 항상 배열입니다.

응답 예시: 무매칭

GET https://api.ns3.ai/newscover?q=pemex

무매칭도 HTTP 200에 matched: false로 반환됩니다: 무매칭은 에러가 아닙니다. 일부 키워드만 매칭되면 매칭·무매칭 항목이 같은 배열에 함께 나옵니다.

HTTP 상태 코드

코드
의미

200

정상 조회 (무매칭 포함)

400

잘못된 요청. 예: 키워드 5개 이상: { "error": "Too many keywords. Maximum 4 keywords per request." }

7. 응답 필드 레퍼런스 (두 모드 공통)

필드
타입
설명

results

array

매칭 엔티티당 1개 항목. 항상 배열. q=는 무매칭 키워드도 matched: false 항목으로 포함, headline=은 매칭 엔티티만 반환(없으면 빈 배열)

results[].matched

boolean

매칭 여부

results[].input

string

입력에서 발견된 키워드/엔티티 표기

results[].normalizedKeyword

string

정규화형 (소문자화, 특수문자·공백 제거)

results[].name

string | null

매칭된 엔티티의 표시 이름 (예: "Bitcoin (BTC)"). 무매칭이면 null

results[].category

string | null

엔티티 카테고리 슬러그(소문자: crypto, institutions, nations, currencies, commodities, people 등). 무매칭이면 null

results[].images

array

엔티티의 커버 이미지. 기본은 랜덤 1장, mode=extended면 그룹의 전체 이미지. 무매칭이면 빈 배열

results[].images[].url

string

이미지 URL (만료 없음. 단 이미지 교체·삭제 시 변경될 수 있음)

results[].images[].width

number

가로 픽셀

results[].images[].height

number

세로 픽셀

results[].images[].mimeType

string

포맷 (image/jpeg, image/png 등)

results[].images[].imageId

string

고유 이미지 ID

results[].images[].groupId

string

엔티티 키워드 그룹 ID: 기사 간 엔티티 단위 중복 제거에 활용

results[].message

string

실패 사유 (matched: false일 때만 존재)

이미지는 원본 파일(1750×1000, 1.75:1)로 제공됩니다.

8. 매칭률 · 커버 구성 · 폴백

매칭률

  • headline= 실제 뉴스에서 수집한 영어 헤드라인 5,000건 전건을 API에 직접 입력한 결과, **약 89%**의 헤드라인이 1개 이상의 커버를 반환했습니다.

  • q= (실제 뉴스 300건): 키워드 수를 늘릴수록 매칭률이 상승합니다: 1개 79%, 2개 94%, 3개 98%, 4개 99%. 기사 단위 커버 확보율은 **95%**입니다.

라이브러리는 지속 확장 중이므로 이 수치들은 계속 개선됩니다.

커버 구성 전략

동일 엔티티 키워드는 서버에서 병합되므로, 매칭된 두 결과는 항상 서로 다른 엔티티입니다: 분할 커버에 안전합니다.

구성
방법

단일 이미지

반환된 이미지 1장을 풀 커버로 사용

2분할 커버

두 엔티티의 이미지를 2패널 분할 커버로 배치 (X/트위터 스타일)

적응형

2개 이상 매칭 시 앞의 2개로 분할 커버, 1개면 단일 커버

폴백 규칙

결과
조치

무매칭 (headline= 빈 배열, 또는 q= 전체 matched: false)

자체 폴백 커버 사용

1개 이상 매칭

매칭 이미지로 커버 구성: 폴백 불필요

두 모드 공통 무매칭 판정: results에서 matched: true인 항목이 0개면 무매칭으로 처리하세요. 이 판정은 headline=(빈 배열)과 q=(matched: false 항목 포함) 모두에서 동일하게 동작합니다.

신뢰성 팁: 기본 폴백 이미지를 준비하세요.

9. AI 툴(function calling)로 NewsCover 사용하기

외부 뉴스를 자체 AI로 재편집해 발행한다면, NewsCover를 그 AI의 툴로 등록하세요. 재작성 모델은 이미 기사의 엔티티를 파악하고 있습니다. headline=을 쓰면 헤드라인을 그대로 넘기기만 하면 되므로 키워드 추출 단계가 아예 없습니다.

동작 순서

  1. 재작성 프롬프트에 툴을 등록합니다.

  2. 재작성 중 AI가 툴을 1회 호출합니다: 헤드라인(headline=) 또는 핵심 엔티티(q=)를 전달.

  3. 실제 API 호출은 사용자의 툴 핸들러 코드가 수행하고, 반환된 url을 출력(예: coverImage 필드)에 주입합니다.

툴 정의 예시 (headline=, 권장)

툴 핸들러 예시

(q=를 쓰려면 파라미터를 콤마 구분 keywords로 바꾸고 같은 방식으로 쿼리를 구성하면 됩니다.)

팁

  • url은 모델이 받아쓴 텍스트가 아니라 오케스트레이터 코드에서 툴 응답으로부터 직접 가져오세요 (URL이 긴 해시 문자열이라 모델 전사 오류 위험). 또는 모델은 imageId만 출력하게 하고 URL은 코드에서 주입하세요.

  • 빈 응답 또는 matched: false일 때의 동작(기본 커버로 폴백 등)을 시스템 프롬프트에 정의하세요.

  • 추가 비용은 기사당 툴 호출 1회입니다: 응답은 수백 토큰 수준으로, 전체 재작성 비용 대비 미미합니다.

10. 이미지 라이선스 & 품질 검수

이미지는 주로 위키미디어 공용(Wikimedia Commons)과 위키피디아에서 소싱되며, 퍼블릭 도메인 또는 개방형 라이선스 저작물로 구성됩니다. 편집적 사용(뉴스 보도에서 기업·자산·인물을 식별하는 용도)으로 제공됩니다.

  • 사용자는 이 목적 안에서 게시·크롭·리사이즈·직접 참조(핫링크)가 허용됩니다.

  • 뉴스 보도 외 사용(광고·머천다이즈), 제3자 재판매·재라이선스, 이미지 모음집 형태의 재배포는 허용되지 않습니다.

모든 이미지는 등록 전 다음 검사를 통과합니다:

  • 개별 라이선스 검증 (퍼블릭 도메인 / 개방형 라이선스)

  • 그리드 시스템 규격화 및 표준 커버 비율(1:1, 1.75:1, 1.91:1, 2.5:1) 최적화

  • 배포 전 최종 사람 검수

사용 조건

  • 커버 사용 시 NS3 출처 표기가 필요합니다. 표준 형식은 "NewsCover by NS3"이며, 표기 위치·형식은 NS3 팀과 협의해 조정할 수 있습니다.

Last updated