AI Creator Classification API: Niche, Audience & Brand Fit

If you run a creator marketplace, an agency roster, or a discovery product, the hard part is never fetching the profile — it is *labelling* it. A handle like @natgeo is obvious, but the other 40,000 in your database are not. Which ones are fitness creators versus fitness *brands*? Who is a real person open to paid deals versus a media account that will never reply? Doing this by hand does not scale past a few hundred rows, and a keyword match on the bio is wrong more often than it is right.

The Intelligence API runs a language model over a public Instagram account and hands back one structured object: entity type, account role, content niche and sub-niches, inferred demographics, a brand-fit summary, a commercial-intent read, and any emails it finds. One request, one flat cost, ready to write straight into your creator table. This guide covers the fields, the two model tiers, caching, and how to tag a whole roster in a loop.

What one request gives you

GET /v1/intelligence/profile takes a single q (username, @handle, or instagram.com/... URL) and returns a { data, meta } envelope. The data object is the classification bundle — everything you would otherwise pay a human to tag:

Call it in three lines

Authenticate with Authorization: Bearer $VIREV_API_KEY. Every response carries a meta block — cost, balance, and request_id — so you can log spend per call. Start with curl:

curl "https://api.virev.ai/v1/intelligence/profile?q=natgeo" \
  -H "Authorization: Bearer $VIREV_API_KEY"

const res = await fetch(
  "https://api.virev.ai/v1/intelligence/profile?q=natgeo",
  { headers: { Authorization: "Bearer kb_live_..." } },
);
const { data, meta } = await res.json();

console.log(data.entity_type);       // "person" | "brand" | "organization"
console.log(data.account_role);      // "creator"
console.log(data.content_tags);      // [{ primary: "photography", sub_niches: [...] }]
console.log(data.brand_fit_summary); // a paragraph on which brands suit them
console.log(meta.cost);              // "$0.05"

Choose your model: gpt-5.4-mini vs gpt-5.4

The endpoint defaults to gpt-5.4-mini at $0.05 per call — the right tool for bulk tagging, where you want a consistent niche and role across tens of thousands of rows. When you need sharper judgment — vetting a headline creator, resolving an ambiguous brand-versus-person account, writing a brand-fit read a human will actually trust — pass model=gpt-5.4 for $0.10.

# Higher-reasoning pass on a single high-value account
curl "https://api.virev.ai/v1/intelligence/profile?q=mkbhd&model=gpt-5.4" \
  -H "Authorization: Bearer $VIREV_API_KEY"

Caching and force_refresh

Because the model run is the expensive, slow part, the result is cached per handle. The first request pays the latency; a repeat request for the same account comes back fast instead of re-running the model. That makes re-reads cheap in time — enrich once, then reference the stored classification whenever your UI needs it.

When a creator has genuinely changed — rebranded, switched niches, went from personal to business — pass force_refresh=true to re-run the model against fresh profile data. That bypasses the cache and doubles the cost ($0.10 on mini, $0.20 on gpt-5.4), so trigger it deliberately rather than on every read.

Auto-tag a whole roster

The batch pattern is a plain loop: pull your handles, classify each, and write the fields straight onto your creator records. Use a long timeout to absorb cold-handle latency, and raise_for_status() so failed calls surface loudly instead of silently — remember, they were never billed.

import requests

HEADERS = {"Authorization": "Bearer kb_live_..."}
ROSTER = ["natgeo", "mkbhd", "hormozi", "gymshark"]

def classify(handle: str) -> dict:
    r = requests.get(
        "https://api.virev.ai/v1/intelligence/profile",
        params={"q": handle},   # model defaults to gpt-5.4-mini ($0.05)
        headers=HEADERS,
        timeout=300,            # a cold handle runs an LLM — allow minutes
    )
    r.raise_for_status()        # 404 / 502 / 504 cost you nothing
    return r.json()

for handle in ROSTER:
    body = classify(handle)
    d, m = body["data"], body["meta"]
    tag = d["content_tags"][0]
    print(handle, "->", d["account_role"], "|", tag["primary"], tag["sub_niches"])
    print("   commercial_intent:", d["commercial_intent"], "| spent:", m["cost"])

The emails and social_accounts fields come back on the same call, so tagging and first-pass contact discovery happen together. When you need higher recall on outreach details specifically, follow up with the dedicated email finder endpoint — and if you are assembling the full pipeline, see how it fits in build an influencer discovery tool.