怎么在抖音星图按条件找达人并拿到报价单

要做的事：品牌方想在某个垂类里找一批抖音达人，粉丝量卡在一个区间，近期作品的互动还不错，并且在有人登录星图（巨量星图，抖音官方的达人广场）之前，就想先知道每个人大概要多少钱。做法是按内容在星图搜索并加筛选条件，按“一次植入折合每千次播放多少钱”排序，再把真正要谈的那 5 位的完整报价单拉下来。最后得到一张表：达人、粉丝数、近 30 天互动率、播放中位数，以及他们挂出的每种合作方式、报价（元）、是否接单和结算方式。

不需要星图广告主账号。拿到的是星图在达人主页上展示给广告主的数据，用 API key 调用即可。

分步操作

第一步：带筛选条件搜星图

调用抖音星图达人搜索，query 填关键词。决定结果的几个参数：

• search_by：content（默认）或 name。content 拿关键词去匹配达人发布的内容，所以 query=露营 能搜到昵称里根本没有“露营”两个字的露营博主。name 按昵称匹配，手上已经有一份达人名单时用它。
• followers_min、followers_max：粉丝数区间。
• engagement_min：近 30 天互动率下限，单位是百分比，3 表示 3%。
• gender：female 或 male，不传就是都要。

一次调用最多返回 20 位达人，每次 $0.004。每位达人有 id（星图达人 ID，纯数字）、name、followers、location、gender、星图原文的内容类目 categories、engagement_rate，以及近期日常作品的播放中位数 median_views 和互动中位数 median_engagements。rates 是星图卡片上的两个报价（元）：integrated_video（植入视频，产品放进达人平时风格的视频里）和 custom_video（定制视频，围绕品牌专门拍一条）。

curl -G "https://api.okdata.online/v1/douyin/xingtu/creators/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=露营' \
  --data-urlencode 'followers_min=100000' \
  --data-urlencode 'followers_max=500000' \
  --data-urlencode 'engagement_min=3'

注意单位：筛选参数用百分比，返回的 engagement_rate 却是小数，0.042 就是 4.2%，两者不能直接比。加上 view=full，每位达人的 ext 里还会带星图自己的预估值（星图展示的话），比如 expected_views、cpm_integrated、completion_rate。翻页时把 page.next_cursor 原样作为 cursor 传回去，每一页都是一次新的调用。

第二步：拉完整报价单

搜索卡片上只有两个价格，available 和 settlement 也是空的。抖音星图达人报价接收第一步拿到的星图达人 id，返回报价单上的全部内容，每次 $0.04。星图达人 ID 不是抖音账号 ID，也不是 sec_uid，所以一律从搜索结果里取。

返回内容有 creator_id、url（达人的星图主页）、industries（星图标注的行业）和 rates。每一项报价包括：

• type：integrated_video、custom_video，其他合作方式（比如共创任务）统一记为 other。
• name：星图自己的叫法，比如“植入视频”。
• price 和 currency（CNY）。星图没公开价格时 price 为 null。
• available：为 true 表示达人现在接这类单。
• settlement：结算方式，星图原文，比如“固定价格”。

curl -G "https://api.okdata.online/v1/douyin/xingtu/creators/rates/get" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'id=7192045836617285643'

第三步：用 Python 排序并汇总报价

下面的脚本搜索一次，按“植入视频报价 ÷ 播放中位数 × 1000”排序，给最划算的 5 位拉报价单，每种合作方式写一行 CSV。SHORTLIST 同时也是第二步的花费上限。

import csv
import os
import requests

API = "https://api.okdata.online"
HEADERS = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
SHORTLIST = 5  # 拉几份报价单；每份一次调用


def get(path, **params):
    body = requests.get(API + path, headers=HEADERS, params=params, timeout=60).json()
    if body["code"] != "ok":
        raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")
    return body["data"]


def per_1k_views(creator):
    price = next((r["price"] for r in creator["rates"] or [] if r["type"] == "integrated_video"), None)
    views = creator["median_views"]
    return price / views * 1000 if price and views else float("inf")


found = get("/v1/douyin/xingtu/creators/search", query="露营", followers_min=100000,
            followers_max=500000, engagement_min=3)["items"]
shortlist = sorted(found, key=per_1k_views)[:SHORTLIST]

with open("xingtu_rates.csv", "w", newline="", encoding="utf-8-sig") as f:
    out = csv.writer(f)
    out.writerow(["creator", "xingtu_id", "followers", "engagement_rate", "median_views",
                  "offering", "type", "price_cny", "open", "settlement"])
    for c in shortlist:
        card = get("/v1/douyin/xingtu/creators/rates/get", id=c["id"])["item"]
        for r in card["rates"]:
            out.writerow([c["name"], c["id"], c["followers"], c["engagement_rate"], c["median_views"],
                          r["name"], r["type"], r["price"], r["available"], r["settlement"]])

用 utf-8-sig 编码，Excel 打开中文不会乱码。如果要给 20 位达人拉报价单，第二步是 $0.80。

注意事项

• 这是挂牌价，不是成交价。 星图展示的是达人自己挂出的价格，平台服务费、折扣和打包价都要在星图下单时才确定。
• 只有入驻星图的达人才搜得到。 没入驻星图、或者没开通商单的达人不会出现。报价单为空的 ID 会返回 not_found，不扣费。
• 空字段有原因可查。 星图搜索不提供抖音号，所以 username 为 null，原因写在 meta.unavailable 里。account_id（有的话）是达人的抖音数字用户 ID，不是 sec_uid。
• 重试不会重复扣费。 每次调用带一个 Idempotency-Key 请求头。24 小时内同样的请求配同样的 key，会直接拿回上次的结果，meta.replayed 为 true，不再扣费。
• 有些数据只在星图后台。 受众画像（年龄、性别、城市）和达人接过的历史订单不在这些字段里，签约前去星图后台核对。
• 报价会变。 发 brief 的当天再拉一次报价单。

如果是给一份现成的达人名单查价，而不是找新达人，看怎么批量查星图达人报价。想看入围达人发过的视频，先拿到他的 sec_uid：怎么获取抖音 sec_uid。

{
  "endpoint": "douyin.xingtu.creators.search",
  "params": {
    "query": "户外"
  },
  "idempotency_key": "<新的 UUID>"
}