> For the complete documentation index, see [llms.txt](https://docs.flash.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.im/docs/api-reference/newscover-api.md).

# NewsCover API

Cover images matched to your headlines or keywords.

{% hint style="info" %}
`GET /v1/newscover` · header `Authorization: Bearer sk_live_...` · call it from your server · roughly 4,000 entities and 10,000 covers
{% endhint %}

## Overview

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. FLASH news already ships with covers attached; this API puts the same covers on **your own news**: your AI-rewritten feed, your editorial desk, your text-only sources. The library currently holds roughly **4,000 entities** and **10,000 covers**, organized into the following categories.

<table data-search="false"><thead><tr><th>Category</th><th>Examples</th></tr></thead><tbody><tr><td>Crypto</td><td>Bitcoin, Ethereum, Solana</td></tr><tr><td>Corporate &#x26; Brands</td><td>Tesla, Apple, Binance</td></tr><tr><td>Nations, states and cities</td><td>United States, Japan, Texas, Tokyo</td></tr><tr><td>Currencies</td><td>Dollar, Yen, Euro</td></tr><tr><td>Commodities</td><td>Gold, Oil, Copper</td></tr><tr><td>People</td><td>Major politicians, CEOs, investors</td></tr><tr><td>Institutions · Regulation · Indicators · Concepts</td><td>Fed, SEC, tariffs, CPI</td></tr><tr><td>Instruments</td><td>S&#x26;P 500, KOSPI, VIX, Treasuries, spot ETFs</td></tr></tbody></table>

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FybpSPt8C1b6OLzS0GWXs%2FNEWSROOM-NEWSCOVER.png?alt=media&amp;token=c7c19bdc-b654-4b8a-9f01-6796ab6d3c6f" alt=""><figcaption><p>Search the NewsCover</p></figcaption></figure>

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FbLyEt7sTBzqS5rYLZ3xy%2FNEWSROOM-NEWSCOVER-Trump.png?alt=media&amp;token=4a9afadd-d301-4b41-a828-fd5141cdadae" alt=""><figcaption><p>Search Results (Donald Trump)</p></figcaption></figure>

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FzQLXVUc87VECgxsBPIyA%2FNEWSROOM-NEWSCOVER-Gold.png?alt=media&amp;token=2c521942-8dd6-425d-849e-efe88362d962" alt=""><figcaption><p>Search Results (Gold)</p></figcaption></figure>

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FBnJzd0T0w5UUAln6wNqY%2FNEWSROOM-NEWSCOVER-hyper.png?alt=media&amp;token=4b1bbdcf-926e-459c-a194-f0281356dc6d" alt=""><figcaption><p>Search Results (Hyperliquid)</p></figcaption></figure>

<a href="https://app.flash.im/newsroom/newscover-library" class="button primary">Newscover Library -></a>

**Send tickers in upper case** (`BTC`, not `btc`). A lower-case ticker is read as an ordinary word and will not match a ticker, so do not normalize your keywords to lower case. Full names are case-insensitive.

It covers **every constituent of the CMC 500, Nasdaq 100, and S\&P 500**, plus most major global brands and the entities that appear most often in crypto and economic news.

### Standardized covers and the grid system

Every cover is produced as a high-quality image normalized by our grid system (person, symbol, wordmark, and object layouts), passes the grid check, and is deployed only after a final human review.

<div><figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FtWDEmS3cDzet7k6bPbJ8%2FChangpengZhao-person-10.jpg?alt=media&#x26;token=8be55117-ff64-4070-a3a8-fac176cbc6e3" alt=""><figcaption></figcaption></figure> <figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FiSSjwo12WbKH3GpVNgW6%2FGuide_3.png?alt=media&#x26;token=a71d9275-4085-4d07-88b3-28b12a2f5d21" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FYn0dkhOiuAv3wTabqCqS%2FGuide_1.jpg?alt=media&#x26;token=3dfa2be7-a0ec-40a3-805d-867fd70e1c69" alt=""><figcaption></figcaption></figure> <figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FMuOIjYD7bejtxlERC8fx%2FGuide_2.jpg?alt=media&#x26;token=3f9d5d5f-8825-40bc-84e2-98171cbc8f36" alt=""><figcaption></figcaption></figure></div>

## Where to use it

| Your UX surface       | How                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| News feed thumbnails  | Many source articles ship without an image; `headline=` fills the gap with a correct, licensed cover |
| Editorial desk        | `q=` + `mode=extended`: the editor picks from every cover the entity group holds                     |
| AI-rewriting pipeline | Register as a tool; one call per article, no keyword extraction (see the AI tool section)            |

## Choosing a search mode

|                   | `headline=` headline search     | `q=` keyword search                                                    |
| ----------------- | ------------------------------- | ---------------------------------------------------------------------- |
| Input             | The headline, as-is             | Keywords you extracted, comma-separated, up to **4** (5 or more = 400) |
| Entity extraction | NewsCover engine (automatic)    | You (manual)                                                           |
| Matching          | Strict: minimizes false matches | Loose: favors discoverability                                          |
| Your workload     | None: just forward the text     | Core-keyword selection needed                                          |
| Fit               | Automation, AI-rewritten feeds  | Human editing, clear keywords                                          |

{% hint style="info" %}
Rule of thumb: if a machine (or an AI rewriter) produces your feed, use `headline=`. If a person picks the keywords, either works.
{% endhint %}

## Usage patterns

There is nothing to extract on your side: send the headline as-is, or the keywords a person picked. Same key as the rest of the API; **call it from your server**.

One template per mode; the key header applies to both:

```
GET https://api.flash.im/v1/newscover?headline={headline text}
GET https://api.flash.im/v1/newscover?q={keyword 1},{keyword 2}&mode={extended}
Authorization: Bearer sk_live_...
```

**1. Automated feed** (headline mode, one call per article)

```
GET https://api.flash.im/v1/newscover?headline=Bitcoin surges as SEC approves ETF
```

Call once per article in your publishing pipeline and use the first entity's cover as the article image (the first entity is usually the primary subject). On no-match, fall back to your default image or publish the story as text-only. For AI-rewriting pipelines, register this as a tool (next section).

**2. Editorial pick** (keyword mode + extended)

```
GET https://api.flash.im/v1/newscover?q=bitcoin&mode=extended
```

Returns every cover the entity group holds; the editor picks the one that fits the story. This is the API version of browsing the library.

**3. Split cover for a two-entity story**

```
GET https://api.flash.im/v1/newscover?q=SEC,Bitcoin
```

Two matched results are always two different entities (same-entity keywords merge server-side), so render the first two as a two-panel split cover, the style widely used on X.

## Rules

* `headline=` scans the first 250 characters and returns covers for up to 5 entities in the order they appear; the first is usually the primary subject. Send headlines as-is; do not change their casing
* `q=` ignores case for full names, and keywords resolving to the same entity merge into one result. This enables a backup-keyword pattern (`?q=SamBankmanFried,BankmanFried,SBF` returns one result for whichever spelling is registered). Tickers are the exception: send them in upper case
* Minor spelling differences resolve to the same entity: `Polymarket` / `poly market` / `poly-market` / `POLY_MARKET` all match Polymarket
* Add `mode=extended` to get **all** covers of the matched entity group in `images`, instead of one randomly assigned cover from the several covers registered to that group
* English only. Proper entity names or tickers match (`Bitcoin`, `BTC`, `Fed`); generic phrases do not (`crypto market crash`)

## Response

**Response** (single keyword matched)

```json
{
  "results": [
    { "matched": true,
      "input": "bitcoin",
      "name": "Bitcoin (BTC)",
      "category": "crypto",
      "images": [
        { "url": "https://.../7y9bQA7UG...",
          "width": 1750, "height": 1000, "mimeType": "image/jpeg",
          "imageId": "7y9bQA7UG2t5...", "groupId": "68c028423b0441..." } ] }
  ]
}
```

**Response** (`q=` no match; a miss is HTTP 200, not an error)

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

* Images are the original **1750x1000** file. `url` is non-expiring but can change if a cover is replaced; `groupId` identifies the entity's cover group (use it to deduplicate across articles)
* **No-match**: `headline=` returns an empty `results` array; `q=` returns `matched: false` items with a `message`. A check that works in both modes: treat the response as a no-match when `results` has zero items with `matched: true`

## Cover composition & fallback

How many entities matched decides the composition:

```mermaid
flowchart LR
    A["Request<br/>headline= or q="] --> B{"matched entities"}
    B -->|"2 or more"| C["Split cover<br/>first two, side by side"]
    B -->|1| D["Single cover"]
    B -->|0| E["Your fallback image,<br/>or publish text-only"]
```

Using the first cover alone as a single is always a correct answer. Same-entity keywords are merged server-side, so any two matched results are always two different entities: safe for split covers.

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FwxgZlRxjaNbLOhphWWcT%2FNEWSROOM-Modal.png?alt=media&amp;token=dfa3f408-e1f8-4b83-ab75-3bdb354812bd" alt=""><figcaption><p>Split cover example, two entities side by side</p></figcaption></figure>

<figure><img src="https://2934076593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7M9iZ2Kg8fDpH37gsTL3%2Fuploads%2FLAPxdR9JqEM0SWXuLai8%2Fsmaple.jpg?alt=media&#x26;token=87e0325f-944c-424e-af85-a31006042085" alt=""><figcaption><p>NewsCover Support Ratios (1:1 - 1.75:1 - 1.91:1 - 2.5:1)</p></figcaption></figure>

## 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.

{% stepper %}
{% step %}

### Register the tool

Add the tool definition to your rewriting prompt.

```json
{
  "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"]
  }
}
```

{% endstep %}

{% step %}

### The AI calls it once

While rewriting, the model calls the tool once, passing the headline.
{% endstep %}

{% step %}

### Your handler injects the URL

Your tool handler makes the actual API call and injects the returned `url` into the output (e.g. a `coverImage` field).

```js
async function get_news_cover(headline) {
  const res = await fetch(
    'https://api.flash.im/v1/newscover?headline=' + encodeURIComponent(headline),
    { headers: { 'Authorization': 'Bearer ' + process.env.FLASH_API_KEY } }
  );
  return await res.json();
}
```

{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Tips:** take the `url` 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 code. Define in your system prompt what the AI should do on a no-match (e.g. fall back to your default cover). The added cost is one tool call per article.
{% endhint %}

## Errors

200 (including no-match) · 400 (more than 4 keywords) · 401 (missing or invalid key) · 429 (rate limit; retry after `Retry-After`)

## FAQ

<details>

<summary>Can I use covers in ads or merchandise?</summary>

No. Covers are licensed for editorial use only: identifying the company, asset, or person in news coverage. Advertising, merchandise, resale, and redistribution as a collection are not permitted. See License & credit below.

</details>

<details>

<summary>Can I skip the credit?</summary>

Surfaces that display covers carry **\[Powered by FLASH]**: the bottom of the news block, the module footer, or the modal footer are the standard positions. Social media posts are the exception: a post you publish to a social account does not need the credit.

</details>

<details>

<summary>Does the watermark affect image quality?</summary>

No. The provenance watermark is invisible, carries no user data, and survives cropping, re-encoding, and screenshots. It exists so the origin of a FLASH cover can be verified.

</details>

<details>

<summary>Can I call this API from the browser?</summary>

Call it from your server. Your API key must not ship in client-side code.

</details>

<details>

<summary>Can an editor pick a specific cover instead of the assigned one?</summary>

Yes. Add `mode=extended` to get every cover the matched entity group holds, render the choices, and let the editor pick.

</details>

## License & credit

{% hint style="warning" %}
Covers are licensed for **editorial use**: identifying the company, asset, or person in news coverage. Within this purpose, publishing, cropping, resizing, and hotlinking are allowed. Use outside news coverage (advertising, merchandise), resale or re-licensing, and redistribution as an image collection are not permitted.

Credit covers as <mark style="color:blue;">**\[Powered by FLASH AI]**</mark>

Every cover carries an **invisible provenance watermark** that survives cropping, re-encoding, and screenshots. It identifies the image as a FLASH asset for origin verification; it carries no user data and does not affect image quality.
{% endhint %}