BrightBean docs

Quickstart

In under five minutes you’ll have an API key and a working scoring call.

1. Create an account and grab a key

Sign up at app.brightbean.xyz (Google, Apple, GitHub, or email). New accounts start with 350 credits on the free tier. Open API Keys and create a key — it looks like bb_<32-hex-characters>. Copy it once; you can’t view it again.

export BRIGHTBEAN_API_KEY="bb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Make your first call

Score a video title and thumbnail together. This costs 3 credits.

cURL

curl -X POST https://api.brightbean.xyz/v1/score/packaging \
  -H "Authorization: Bearer $BRIGHTBEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "I bought a $0.99 keyboard so you don'\''t have to",
    "thumbnail_url": "https://i.ytimg.com/vi/EXAMPLE/hqdefault.jpg"
  }'

The server auto-detects the scoring mode (title-only, thumbnail-only, or combined) from your inputs. The niche is also auto-detected from the title — you don’t pass it.

Python

pip install brightbean
from brightbean import BrightBean

with BrightBean() as client:
    result = client.score(
        title="I bought a $0.99 keyboard so you don't have to",
        thumbnail_url="https://i.ytimg.com/vi/EXAMPLE/hqdefault.jpg",
    )
    print(f"score={result.score:.2f} percentile={result.percentile} niche={result.niche_label}")

The SDK reads BRIGHTBEAN_API_KEY from your environment by default.

TypeScript

npm install brightbean
import { BrightBean } from "brightbean";

const client = new BrightBean({ apiKey: process.env.BRIGHTBEAN_API_KEY });

const result = await client.score({
  title: "I bought a $0.99 keyboard so you don't have to",
  thumbnailUrl: "https://i.ytimg.com/vi/EXAMPLE/hqdefault.jpg",
});

console.log(result.score, result.percentile, result.niche_label);

CLI

npm install -g @brightbean/cli
brightbean auth status

# Title only (1 credit)
brightbean score --title "I bought a \$0.99 keyboard so you don't have to" --pretty

# Title + local thumbnail file (3 credits)
brightbean score --title "..." --thumb thumb.jpg --pretty

The CLI’s --thumb flag takes a local file path (or - for stdin), not a URL. To score by URL, use the REST/SDK examples above.

3. Read the response

You’ll get back:

{
  "score_id": "01J7K4...",
  "score": 0.81,
  "percentile": 81,
  "raw_score": 1.42,
  "mode": "combined",
  "niche_slug": "tech-tutorials",
  "niche_label": "Tech Tutorials",
  "niche_confidence": 0.93
}

score is a calibrated 0–1 CTR percentile (with percentile as the rounded 0–100 view). raw_score is the continuous pre-calibration sigmoid output — useful for fine-grained comparisons that the rounded percentile would flatten. mode reflects what the server detected: "title", "thumbnail", or "combined". niche_* describes the auto-detected niche.

Over MCP the same payload also carries credits_remaining so the agent can budget itself.

4. Where to go next