NewsCover Library

NewsCover Library

1. Overview

NewsCover Library ("NewsCover") is a service that provides cover images that fit the news. Send a keyword or a headline, and it instantly returns matching covers from the library. The library currently holds roughly 3,000 entities and 10,000 covers, organized into the following categories.

Two ways to use (web & API):

Mode

You send

Best for

Headline search headline=

The raw headline text, unchanged

Automation and AI-rewriting pipelines (no keyword extraction needed)

Keyword search q=

Keywords you selected (comma-separated, up to 4)

Editors composing covers exactly as intended

Both modes use the same endpoint with a different query parameter and share one response schema (Section 7). No authentication, no rate limit, and CORS enabled (Access-Control-Allow-Origin: *), so you can call the API directly from browser front-ends as well as servers.

Headline search: GET https://api.ns3.ai/newscover?headline={headline text}
Keyword search: GET https://api.ns3.ai/newscover?q={keyword1,keyword2,keyword3,keyword4}

Cover ratios and representative platforms

Ratio

Formats

Representative use

1.75:1 (original, 1750×1000)

Single · Split

X (Twitter) timeline image

1:1

Single

Square thumbnails, in-app cards

1.91:1

Single · Split

OG image (social link preview), web standard 1200×630

2.5:1

Single · Split

Wide news-feed banner

A Split cover places two entities' covers side by side as a single two-panel cover (the style widely used on X/Twitter). Because every cover passes the grid check, the subject stays correctly placed in both single and split layouts, with no visual mismatch between the two covers.

2. Choosing a Search Mode: `headline=` vs `q=`

headline= headline search

q= keyword search

Input

The headline / breaking-news line, as-is

Keywords you extracted, comma-separated

Entity extraction

NewsCover library (automatic)

Editor (manual)

Matching

Strict: minimizes false matches

Loose: favors discoverability

Editor workload

None: just forward the text

Core-keyword selection needed

Fit

Automation, AI-rewritten feeds

Human editing, clear keywords

Headline search derives covers straight from an existing headline, with no extra workflow. No-match and over-match can occur at a low rate, so a final human review is recommended to guarantee a complete result for readers.

Keyword search returns only the entities the editor selects, so covers are composed exactly as intended.

The precision of headline search is structural. Headline text cannot be controlled, so stricter matching is applied than in keyword search:

Tickers are case-sensitive; names are case-insensitive. In "Bitcoin trades near record highs", lowercase near is just the word "near" and returns nothing, while uppercase NEAR matches the NEAR ticker. Apple or apple is a name and matches the company either way. (Therefore, send headlines as-is; do not change their casing.)
Edge-case handling is built in. Over-match patterns identified by simulating thousands of real headlines are reflected in the engine and the keyword dictionary. For example, a currency used as an amount unit ("Raises Funding Worth 100 Million Yuan") does not trigger a cover.

q= mode is deliberately loose: because you chose the keywords on purpose, even lowercase near returns the NEAR cover.

Rule of thumb: if a machine (or an AI rewriter) produces your feed, use headline=. If a person picks the keywords, either works.

3. Keyword Search Guide

Minor differences in spelling resolve to the same entity. Case, spaces, hyphens, and special characters do not affect matching:

Input

Match

Polymarket / poly market / poly-market / POLY_MARKET

Polymarket

$BTC / btc

BTC

Bank of England / bankofengland

Bank of England

Tips for a higher match rate

Use proper entity names or tickers: Bitcoin, BTC, Tesla, Fed, Japan
Generic nouns and descriptive phrases will not match: crypto market crash, price surge
Keywords are supported in English only

When there is no match: the Web shows "No results found." and the API returns the mode-specific no-match response (see Sections 5 and 6).

4. NewsCover Web (for Editors)

URL: https://ns3.ai/newscover

Type a keyword or headline into the search box (English)
All images in the matched group are displayed
Check the ratio previews for each image: 1:1 square / 1.75:1 single·split / 1.91:1 single·split / 2.5:1 single·split / original ratio
Click the Download Image button to save the file, or click the copy icon to copy the image URL

Split previews show the two-panel split cover style widely used on X (Twitter) and similar platforms.

5. Headline Search API

Send the raw headline; the engine extracts the entities and returns a cover for each.

GET https://api.ns3.ai/newscover?headline={headline text}
GET https://api.ns3.ai/newscover?headline={headline text}&mode=extended

Behavior

URL-encode the text (spaces as %20 or +). Browsers and HTTP libraries do this automatically.
The first 250 characters of the headline are scanned. (Longer input is accepted, but entities after the 250th character are not matched.)
Up to 5 entities are returned, in the order they appear in the headline. The first entity is most likely the primary subject, so use it when you need a single representative cover.
Entity names of up to three words are matched ("Bank of England", "Ki Young Ju"). Punctuation is handled naturally: "Bitcoin (BTC)", "BTC," and "Trump's" all match their entities. A name and its ticker in the same headline merge into one result.
images is an array. By default it holds one randomly assigned cover per matched entity group, so the same headline always returns the same entities but the specific cover image can differ between calls.
Add mode=extended to return all covers the group holds in the images array. This gives you the same result as the web search via the API, so the editor can pick from all returned images.
When nothing matches, results is an empty array. See the no-match example below.

Response example: two entities matched

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

{
  "results": [
    {
      "matched": true,
      "input": "Bitcoin",
      "normalizedKeyword": "bitcoin",
      "name": "Bitcoin (BTC)",
      "category": "crypto",
      "images": [
        {
          "url": "https://assemble-ai-files.s3.amazonaws.com/2z4Lwzp9Mq...",
          "width": 1750,
          "height": 1000,
          "mimeType": "image/jpeg",
          "imageId": "2z4Lwzp9MqNT8mt7y7vunAd2Bs147XDpqgkTUeKCGyMM",
          "groupId": "68c028423b04413d9f9679c2"
        }
      ]
    },
    {
      "matched": true,
      "input": "SEC",
      "normalizedKeyword": "sec",
      "name": "U.S. Securities and Exchange Commission (SEC)",
      "category": "institutions",
      "images": [
        {
          "url": "https://assemble-ai-files.s3.amazonaws.com/6jMTXdrgPL...",
          "width": 1750,
          "height": 1000,
          "mimeType": "image/jpeg",
          "imageId": "6jMTXdrgPLXmZLcr9NgN2PKwqSRZrnrXeqg7STMxETGM",
          "groupId": "68c05a44c34f4a2bb67c4b44"
        }
      ]
    }
  ]
}

input echoes the entity form found in the headline. Identify which entity matched by name and groupId. groupId can also be used to check whether the same entity's cover repeats across articles.

Response example: no match

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

{ "results": [] }

When no entity matches, the array is empty. (This differs from q=, which returns an explicit matched: false item per keyword. See Section 6.) Prepare your own fallback cover for this case.

6. Keyword Search API

Send keywords you extracted.

GET https://api.ns3.ai/newscover?q={keyword1,keyword2,...}
GET https://api.ns3.ai/newscover?q={keyword1,keyword2,...}&mode=extended

Query rules

Up to 4 keywords, separated by commas. 5 or more returns HTTP 400.
URL-encode keywords: spaces as %20/+, & as %26. An unencoded space fails the request, and an unencoded & silently truncates the query. (Tip: sending keywords with no spaces, like bankofengland, sidesteps encoding entirely. Case is ignored in q=.)
images is an array holding one randomly assigned cover by default, so the same keyword may return a different image on each call.
Add mode=extended to return all covers the group holds in the images array.

Same-entity merging & backup keywords. Keywords that resolve to the same entity merge into one result, so the response can have fewer items than the keywords you sent: always map by input. This enables a backup-keyword pattern: send several spellings of one entity (e.g. ?q=SamBankmanFried,BankmanFried,SBF) and whichever is registered will match, you still get just one result, and there is no risk of receiving the same subject twice.

Response example: single keyword

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

{
  "results": [
    {
      "matched": true,
      "input": "bitcoin",
      "normalizedKeyword": "bitcoin",
      "name": "Bitcoin (BTC)",
      "category": "crypto",
      "images": [
        {
          "url": "https://assemble-ai-files.s3.amazonaws.com/7y9bQA7UG...",
          "width": 1750,
          "height": 1000,
          "mimeType": "image/jpeg",
          "imageId": "7y9bQA7UG2t5GCmGdsog3V366UAA1P8oKz8VbCuFHbC5",
          "groupId": "68c028423b04413d9f9679c2"
        }
      ]
    }
  ]
}

results is always an array, even for a single keyword.

Response example: no match

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

{
  "results": [
    {
      "matched": false,
      "input": "pemex",
      "normalizedKeyword": "pemex",
      "name": null,
      "category": null,
      "images": [],
      "message": "No matching image found"
    }
  ]
}

A no-match is also returned as HTTP 200 with matched: false: a miss is not an error. When only some keywords match, matched and unmatched items appear together in the same array.

HTTP status codes

Code

Meaning

200

Successful lookup (including no-match)

400

Malformed request. e.g. more than 4 keywords: { "error": "Too many keywords. Maximum 4 keywords per request." }

7. Response Field Reference (shared by both modes)

Field

Type

Description

results

array

One item per matched entity. Always an array. q= also includes unmatched keywords as matched: false items; headline= returns matched entities only (empty array if none)

results[].matched

boolean

Whether this item matched

results[].input

string

The keyword / entity form found in the input

results[].normalizedKeyword

string

Normalized form (lowercased, special characters and spaces removed)

results[].name

string | null

Display name of the matched entity (e.g. "Bitcoin (BTC)"); null when there is no match

results[].category

string | null

Entity category slug, lowercase (crypto, institutions, nations, currencies, commodities, people, etc.); null when there is no match

results[].images

array

Cover images for the entity. One randomly assigned image by default; all of the group's images with mode=extended. Empty array when there is no match

results[].images[].url

string

Image URL (non-expiring; may change if the image is replaced or removed)

results[].images[].width

number

Width in px

results[].images[].height

number

Height in px

results[].images[].mimeType

string

Format (image/jpeg, image/png, etc.)

results[].images[].imageId

string

Unique image ID

results[].images[].groupId

string

ID of the entity's keyword group: use for entity-level deduplication across articles

results[].message

string

Reason for failure (present only when matched: false)

Images are delivered as the original file (1750×1000, 1.75:1).

8. Match Rate · Cover Composition · Fallback

Cover composition strategies

Same-entity keywords are merged server-side, so any two matched results are always two different entities: safe for split covers.

Composition

How

Single image

Compose the cover with one representative image only

Two-image split

Place two entities' images in a two-panel split cover (X/Twitter style)

Adaptive (Recommend)

If two or more images match, split-cover the first two; if only one matches, use a single-image cover. If no images are returned, use your own fallback image or publish the story as text-only news without a cover

Fallback rules

Result

Action

No match (headline= empty array, or all q= keywords matched: false)

use your own fallback cover or publish the story as text-only news without a cover

One or more matched

Compose the cover from the matched images

A no-match check that works in both modes: treat the response as a no-match when results contains zero items with matched: true. This single check behaves identically for headline= (empty array) and q= (which includes matched: false items).

Reliability tip: prepare a default fallback image, or a text-only news UI for stories without a cover.

Match rate

headline=: We fed 5,000 real-world English news headlines directly into the API; about 89% of headlines returned at least one cover.
q= (300 real news articles): The match rate rises with keyword count: 79% with 1 keyword, 94% with 2, 98% with 3, and 99% with 4. At the article level, 95% of articles secured a cover.

The library expands continuously, so these figures keep improving.

9. Using NewsCover as an AI Tool (function calling)

If you re-edit external news with your own AI before publishing, register NewsCover as a tool for that AI. The rewriting model has already identified the article's entities. With headline=, it simply passes the headline through, so there is no keyword-extraction step at all.

How it works

Register the tool in your rewriting prompt.
While rewriting, the AI calls the tool once, passing the headline (headline=) or the core entities (q=).
The actual API call is made by your tool handler code, which injects the returned url into the output (e.g. a coverImage field).

Example tool definition (headline=, recommended)

{
  "name": "get_news_cover",
  "description": "Returns news cover images for the entities in a news headline. Pass the article's headline text as-is; the service extracts entities and returns one cover per entity.",
  "parameters": {
    "type": "object",
    "properties": {
      "headline": {
        "type": "string",
        "description": "The article headline in English, unchanged."
      }
    },
    "required": ["headline"]
  }
}

Example tool handler

async function get_news_cover(headline) {
  const res = await fetch(
    'https://api.ns3.ai/newscover?headline=' + encodeURIComponent(headline)
  );
  return await res.json();
}

(To use q=, swap the parameter for comma-separated keywords and build the query the same way.)

Tips

Take the url directly from the tool response in your orchestrator code, not from text the model transcribed (URLs are long hash strings, so model transcription is error-prone). Alternatively, have the model output only the imageId and inject the URL in your code.
Define in your system prompt what the AI should do on an empty response or matched: false (e.g. fall back to your default cover).
The added cost is one tool call per article: the response is a few hundred tokens, negligible relative to the overall rewriting cost.

10. Image License & Quality Review

Images are sourced primarily from Wikimedia Commons and Wikipedia, and consist of public-domain or openly licensed works. They are provided for editorial use: identifying the company, asset, or person in news coverage.

Within this purpose, publishing, cropping, resizing, and direct referencing (hotlinking) are allowed.
Use outside news coverage (advertising, merchandise), resale or re-licensing to third parties, and redistribution as an image collection are not permitted.

Every image passes the following checks before registration:

Individual license verification (public domain / open license)
Grid-system normalization and optimization for the standard cover ratios (1:1, 1.75:1, 1.91:1, 2.5:1)
A final human review before deployment

Usage requirements

Covers must be credited to NS3. The standard form is [NewsCover by NS3] alternative placements or formats can be agreed with the NS3 team.

Last updated 0 minutes ago