TikTok Influencer Discovery API Workflow

import os, requests, json
from collections import defaultdict

TOKEN = os.environ["SCAVIO_API_KEY"]
AUTH = {"Authorization": f"Bearer {TOKEN}"}
BASE = "https://api.scavio.dev/api/v1/tiktok"

def discover_creators(niche_queries: list, min_plays: int = 10000) -> dict:
    """Find creators posting about a niche. Cost: 1 credit per query."""
    creators = defaultdict(lambda: {"videos": [], "total_plays": 0})

    for query in niche_queries:
        resp = requests.post(f"{BASE}/search", headers=AUTH,
            json={"query": query, "count": 20})
        videos = resp.json().get("videos", [])

        for v in videos:
            plays = v.get("stats", {}).get("playCount", 0)
            if plays < min_plays:
                continue
            username = v.get("author", {}).get("uniqueId", "")
            if not username:
                continue
            creators[username]["videos"].append({
                "desc": v.get("desc", "")[:80],
                "plays": plays,
                "likes": v.get("stats", {}).get("diggCount", 0),
                "shares": v.get("stats", {}).get("shareCount", 0),
            })
            creators[username]["total_plays"] += plays

    return dict(creators)

# 5 queries = 5 credits = $0.025
creators = discover_creators([
    "skincare routine 2026",
    "best moisturizer dry skin",
    "dermatologist approved skincare",
    "affordable skincare products",
    "skincare over 30",
])

def enrich_creators(creators: dict, top_n: int = 20) -> list:
    """Get full profiles for top creators. Cost: 1 credit each."""
    # Sort by total plays
    sorted_creators = sorted(
        creators.items(), key=lambda x: x[1]["total_plays"], reverse=True
    )[:top_n]

    enriched = []
    for username, data in sorted_creators:
        resp = requests.post(f"{BASE}/user/info", headers=AUTH,
            json={"username": username})
        profile = resp.json()
        user = profile.get("user", {})
        stats = profile.get("stats", {})

        enriched.append({
            "username": username,
            "nickname": user.get("nickname", ""),
            "verified": user.get("verified", False),
            "followers": stats.get("followerCount", 0),
            "following": stats.get("followingCount", 0),
            "total_likes": stats.get("heartCount", 0),
            "video_count": stats.get("videoCount", 0),
            "niche_plays": data["total_plays"],
            "niche_videos": len(data["videos"]),
            "bio": user.get("signature", ""),
        })
    return enriched

# 20 profile lookups = 20 credits = $0.10
profiles = enrich_creators(creators)

def score_creators(profiles: list) -> list:
    """Score and rank creators for campaign fit."""
    for p in profiles:
        # Engagement rate: likes / followers
        p["engagement_rate"] = (
            p["total_likes"] / max(p["followers"], 1) * 100
        )
        # Content frequency: videos per month estimate
        p["est_monthly_posts"] = min(p["video_count"], 30)

        # Composite score
        score = 0
        if 1000 <= p["followers"] <= 500000:  # micro to mid-tier
            score += 2
        if p["engagement_rate"] > 3:
            score += 2
        if p["niche_videos"] >= 3:  # consistent niche content
            score += 2
        if p["verified"]:
            score += 1

        p["fit_score"] = score

    return sorted(profiles, key=lambda x: x["fit_score"], reverse=True)

ranked = score_creators(profiles)

print("Top 5 creators for skincare campaign:")
for c in ranked[:5]:
    print(f"  @{c['username']} | {c['followers']:,} followers | "
          f"{c['engagement_rate']:.1f}% engagement | Score: {c['fit_score']}")

from datetime import datetime

def weekly_discovery_report(brand: str, niche_queries: list) -> dict:
    """Full weekly creator discovery pipeline."""
    creators = discover_creators(niche_queries)
    profiles = enrich_creators(creators, top_n=15)
    ranked = score_creators(profiles)

    return {
        "brand": brand,
        "date": datetime.utcnow().strftime("%Y-%m-%d"),
        "creators_found": len(creators),
        "profiles_enriched": len(profiles),
        "top_recommendations": [
            {"username": c["username"], "followers": c["followers"],
             "engagement": f"{c['engagement_rate']:.1f}%",
             "score": c["fit_score"]}
            for c in ranked[:10]
        ],
        "total_credits_used": len(niche_queries) + len(profiles),
    }

report = weekly_discovery_report("Skincare Brand X", [
    "skincare routine", "moisturizer review", "sunscreen recommendation"
])
print(json.dumps(report, indent=2))