brightbean — Python SDK

Official Python SDK for the BrightBean API. YouTube creator analytics: score titles and thumbnails for click-through-rate, analyze video hooks, benchmark channels and videos against their niche, and surface ranked content opportunities.

Install

pip install brightbean

Requires Python 3.10+.

Quickstart

from brightbean import BrightBean

with BrightBean(api_key="bb_...") as client:
    result = client.score(
        title="10 Tips to Boost Your Coding Productivity",
        thumbnail_url="https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
    )
    print(f"score={result.score:.2f} percentile={result.percentile}")

Async

import asyncio
from brightbean import AsyncBrightBean

async def main():
    async with AsyncBrightBean(api_key="bb_...") as client:
        return await client.score(title="My epic video")

asyncio.run(main())

Every method documented below has the same signature on AsyncBrightBean; just await the call.

API reference

Response objects are typed dataclasses. Field names match the wire format (snake_case). Nullable fields are explicitly annotated … | None.

client.score(...) — packaging CTR

Score a YouTube packaging (title and/or thumbnail) for predicted click-through rate. The server auto-detects the mode from your inputs and charges credits accordingly.

result = client.score(
    title="10 Tips to Boost Your Coding Productivity",
    thumbnail_url="https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
)
print(result.score, result.percentile, result.niche_label)

Parameters

* At least one of title, thumbnail_url, or thumbnail_base64 is required.

Returns PackagingScoreResponse

Cost: 1 credit for title-only, 2 credits for thumbnail-only, 3 credits for combined (the combined mode captures interaction effects the single-input modes miss).

client.video_hook(...) — hook quality of the first ~6 s

Score the first ~6 seconds of a YouTube video for hook quality. Returns a structured analysis with archetype classification, five dimension scores, and actionable strengths / weaknesses / suggestions.

result = client.video_hook(
    youtube_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
)
print(result.primary_archetype, result.overall_score)
print(result.scores.clarity, result.scores.tension)

Parameters

Returns VideoHookScoreResponse

Nested scores:

Cost: 10 credits per call.

client.benchmark_channel(...) — channel vs. niche

Benchmark a YouTube channel against its niche distribution. Fetches the channel's recent videos, classifies the niche, and percentile-ranks engagement and title patterns.

result = client.benchmark_channel(
    url="https://www.youtube.com/@MarquesBrownlee",
)
print(result.niche.slug, result.niche.match_strength)
print(result.channel.engagement_percentiles.overall)

Parameters

Returns BenchmarkChannelResponse — two top-level objects, channel and niche.

channel

niche

Cost: 5 credits per call.

client.benchmark_video(...) — single video vs. niche

Benchmark one YouTube video against its niche distribution.

result = client.benchmark_video(
    url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
)
print(result.video.engagement_percentiles.overall)
print(result.video.title_patterns.fits_niche_patterns)

Parameters

Returns BenchmarkVideoResponse — two top-level objects, video and niche.

video

niche

Same shape as benchmark_channel's niche — slug, name, match_score, match_strength, ratio-keyed engagement distributions, title_patterns with common_niche_phrases. The used_by_channel flag on each common phrase here means "did this single video's title use the phrase"; the serializer field name stays the same across both benchmark endpoints.

Cost: 3 credits per call.

client.niches() — list catalogued niches

List every catalogued YouTube niche for the active research run. Use the slug values as the niche argument to client.content_gaps(...).

result = client.niches()
for n in result.niches:
    print(n.slug, n.gap_count)

Parameters: none.

Returns NicheListResponse

Each NicheSummary:

Cost: 1 credit per call.

client.content_gaps(...) — ranked content opportunities

Return ranked content opportunities (gaps) for a YouTube niche.

result = client.content_gaps(
    niche="python_programming_tutorials",
    gap_type=["underserved", "stale"],   # or just "underserved"
    limit=10,
    min_score=60,
)
for gap in result.gaps:
    print(gap.opportunity_score, gap.canonical_title)

Parameters

Returns ContentGapsResponse

Each gap (ContentGapsItem):

Nested evidence:

Cost: 5 credits per call.

client.me() — account info

Return account info and plan details for the authenticated API key. Free to call.

me = client.me()
print(me.email, me.plan.name, me.credits_remaining)

Parameters: none.

Returns MeResponse

Cost: free (no credits deducted).

client.usage() — credit balance + recent activity

Return the credit balance and recent API activity for the authenticated API key. Free to call.

usage = client.usage()
print(usage.credits_remaining, "/", usage.credits_total)
for entry in usage.recent_activity:
    print(entry.created_at, entry.endpoint, entry.delta)

Parameters: none.

Returns UsageResponse

Each CreditLedgerEntry:

Cost: free (no credits deducted).

Errors

The SDK raises typed exceptions for each documented status code:

All API errors inherit BrightBeanAPIError. Network failures raise NetworkError. Both inherit BrightBeanError for catch-all handling.

Retries

Idempotent GETs (me(), usage()) retry automatically on 5xx and network errors with exponential backoff + jitter. Tune via max_retries:

client = BrightBean(api_key="bb_...", max_retries=5)

POST endpoints and paid GETs are never auto-retried because the server may have charged credits before the network response was lost. Catch RateLimitError or ServiceUnavailableError and back off using retry_after if you need retry semantics.

Configuration

BrightBean(
    api_key="bb_...",                   # required
    base_url="https://api.brightbean.xyz",
    timeout=30.0,                       # seconds, or httpx.Timeout(...)
    max_retries=3,                      # idempotent GETs only
    user_agent=None,                    # override the default UA string
)

base_url defaults to https://api.brightbean.xyz. Override for staging or local testing.

Development

pip install -e .[dev]
openapi-python-client generate \
    --path ../../openapi.yaml \
    --config generator.yaml \
    --meta=none \
    --output-path ./brightbean/_generated \
    --overwrite
pytest && ruff check . && mypy brightbean

The brightbean/_generated/ directory is regenerated from the upstream OpenAPI spec. The hand-written facade (brightbean/_client.py, brightbean/errors.py, brightbean/__init__.py) wraps it to give the ergonomic BrightBean import shape.