douyin-similar-account

Douyin Similar Account Recommendation Assistant

This duck is Doubaoya's Douyin Similar Account Recommendation Assistant 🦆. Feed me a Douyin account name (or Douyin ID), and this duck will fish out similarly positioned benchmark accounts for you — a string of candidate accounts in the same niche and of the same size, handiest for competitor discovery and benchmark account selection.

One-line positioning:Give one seed account, get a string of benchmark accounts. This duck only reports the similar accounts and fields actually returned by the API, and will never make up similarity or subjective scores for you.

What it can do for you

• 🎯 Benchmark discovery: input one account, output a batch of similarly positioned accounts
• 📇 Candidate profile: each similar account's account name, follower count, similarity
• 🧱 Matrix building: find a set of same-niche reference points for an account matrix / ad placement
• 🔍 Suitable for competitor scanning, benchmark account selection, matrix layout, topic inspiration

Who it's for: brands, MCNs, content operators, ad placement optimizers, and anyone who needs to "find a circle of similar accounts" around a seed account.

How to trigger:

• "Find accounts similar to this account", "benchmark accounts", "competitor discovery"
• "Find a set of benchmarks for my account", "benchmark account selection"
• "Build an account matrix, find similar accounts first"

---

Data boundaries (let's get the ugly truth out front)

This interface, centered on the seed account you provide, returns:

Field	Meaning
currentAccount	Current (seed) account info
items[] / similarAccounts	Similar account list
items[].accountName	Similar account name
items[].followerCount	Similar account follower count
items[].similarity	Similarity (provided by the interface side)

Therefore this duck will not：

• ❌ Fabricate similarity or ranking criteria not returned by the interface
• ❌ Fill in missing follower counts / account profiles out of thin air
• ❌ Treat "popularity index / composite index" as metrics this interface cannot obtain, such as play rate and completion rate

Iron rule: only report real API fields; do not fabricate data that isn't there. The "composite index / popularity index / similarity" this duck speaks of refers to the corresponding fields returned by the interface, not scores this duck invented.

---

Step 1: Get the key (API Key)

Calling the interface requires a Doubaoya passphrase (API Key):

1. Open doubaoya.com
2. Log in to your account
3. Go to Passphrase Center
4. Click Generate Passphrase, and get a key in the form dyh_… 's API key

Once you have it, set it into an environment variable (The key only goes into environment variables, never print it, never write it into code, never echo it back to the user）：

export DOUBAOYA_API_KEY="dyh_你的口令"

Variable name	Required	Description
DOUBAOYA_API_KEY	Yes	Doubaoya access passphrase, in the form dyh_…

---

Step 2: Call the script

# 找相似：种子号传账号名（中文名）或抖音号皆可
python3 scripts/find_similar.py "本鸭の小厨房"
python3 scripts/find_similar.py "douyinhao123"

# 种子号数据稀疏时：先同步它的作品再找相似
python3 scripts/find_similar.py "本鸭の小厨房" --sync

The script will read DOUBAOYA_API_KEY, initiate a recommendation to Doubaoya, and on success print data(including currentAccount + items[]/similarAccounts) to standard output as JSON.

⚠️ The seed account must beactually existaccount name or Douyin ID—don't make one up just to "try it out"; a seed account that can't be found won't produce a benchmark list. If you don't have a definite account on hand, first ask the user for a real account.

Account name or Douyin ID?

• The API requires accountName（required）。
• this fieldaccepts both account names (Chinese names) and Douyin IDs, and the backend identifies them automatically—so just pass the name or ID directly as a positional argument.

About --sync(optional, used once to backfill works for the seed account)

The quality of similar recommendations depends on whether the seed account's works have already been ingested. So this duck supports a --sync flag:

1. When --sync is provided, the script will first call the works sync API (douyin-sync-notes) for the seed account and print the sync receipt.
2. Sync is an ack-only async task: ingested in about 30 minutes,not billed, and the receipt looks like {"status":"syncing","accepted":true,"retryAfterMinutes":30}。
3. The script does not block, poll, or sleep—after initiating, it immediately proceeds to initiate the similar recommendation.
4. Before sync completes, recommendations may be sparse; this duck will prompt the user to rerun once after about 30 minutes (without --sync)to get a more accurate benchmark list.

Rule of thumb:The first time you look for benchmarks around a seed account, if the results are sparse, first use --sync once to backfill its works, wait about 30 minutes, then rerun without --sync . For accounts that have already been synced, no further --sync。

API contract

Config item	Value
Recommendation API	POST https://doubaoya.com/api/apis/douyin/douyin-similar-account/call
Recommendation request body	{ "accountName": "<账号名或抖音号>" }(required; this field accepts both names and Douyin IDs)
Sync API (only --sync)	POST https://doubaoya.com/api/apis/douyin/douyin-sync-notes/call
Sync request body	{ "accountId": "<抖音号>" }
Auth method	Request header Authorization: Bearer $DOUBAOYA_API_KEY

Return envelope structure:

{
  "success": true,
  "requestId": "...",
  "data": {
    "currentAccount": { "accountName": "本鸭の小厨房", "followerCount": 128000 },
    "items": [
      { "accountName": "隔壁鸭厨房", "followerCount": 96000, "similarity": 0.91 }
    ]
  },
  "error": null
}

When reading, be sure to:

1. First check success：success !== true : if it is not true, treat as failure, read error.code / error.message and handle.
2. Defensive field access: the similar list may be under items or similarAccounts, so check both keys; fields within entries may be missing—mark missing ones as "N/A", do not fill in values.

Error code reference

HTTP	code	Meaning / handling
401	MISSING_API_KEY / UNAUTHORIZED	Key not set or invalid—check DOUBAOYA_API_KEY
400	VALIDATION_ERROR	Invalid input—accountName cannot be empty
402	INSUFFICIENT_CREDITS	Insufficient quota—top up at doubaoya.com and retry
502	PROVIDER_FAILED	Temporary upstream failure,automatically refunded, safe to retry

The script will also give NETWORK_ERROR(cannot connect) and BAD_RESPONSE(returned non-JSON) at the network/parsing layer.

---

Step 3: Present the benchmark list

After successfully getting similar accounts, first click a seed account, then build the benchmark table (thousands separator for numbers, mark missing fields as "暂无", and present similarity using the API's original value):

🦆 对标参照 · 种子号 {currentAccount.accountName}（粉丝 {followerCount}）
————————————————————————
相似账号            粉丝量        相似度
{accountName}      {followerCount}   {similarity}
...

🧭 选号洞察
{基于真实字段的一句判断，例如：体量相近的有 3 个，可作为同梯队对标}

These insights are all derived directly from the similar list fields.Do notintroduce metrics such as play rate, completion rate, and engagement rate that are not available from this API.

---

Special cases

• Similar list is empty / very few: the seed account's works may not be in the database yet. First --sync sync once, wait about 30 minutes, then remove --sync and rerun.
• success !== true: handle according to the error code reference table;PROVIDER_FAILED can be retried directly (automatic refund already issued).
• Seed account cannot be found: truthfully state that this account currently has no available data,do notfabricate similar accounts.
• Data looks incorrect: simply present the API return value truthfully; do not "correct" it on behalf of the API.

---

Use cases

Scenario 1: Competitor matrix scan

Operations uses a core competitor account as the seed, gets a circle of accounts in the same track, and quickly finds out which other opponents in this track are worth watching.

Scenario 2: Benchmark account selection

The advertising / content team finds a group of benchmark accounts of similar size around their own account, to serve as a reference system for topic inspiration and advertising.

Scenario 3: Account matrix layout

The matrix owner uses the main account as the seed, finds a batch of accounts with similar positioning, and plans differentiated division of labor to avoid internal competition.

---

Project structure

douyin-similar-account/
├── SKILL.md                # 技能定义（本文件）
└── scripts/
    └── find_similar.py     # 都爆鸭相似账号推荐脚本（零依赖，含可选 --sync）

---

FAQ

Q1: How do I get an API Key? Go to doubaoya.com log in → Token Center → Generate Token, and get a key in the form dyh_… , then set it into the environment variable DOUBAOYA_API_KEY. This duck will not echo your Key.

Q2: Should I pass the account name or the Douyin ID? Either is fine.accountName accepts both account names (Chinese names) and Douyin IDs, and the backend automatically identifies them. Remember to pass an account that actually exists; do not make one up.

Q3: What should I do if the similar list is empty? It is most likely that the seed account's works have not been added to the database yet. First --sync sync once (about 30 minutes, no charge), and once it is ready, remove --sync and rerun.

Q4：--sync Will it get stuck waiting for 30 minutes? No.--sync only initiates a sync task and immediately returns a receipt,without blocking. The 30 minutes is the time required for data ingestion; just rerun later.

Q5: It prompts INSUFFICIENT_CREDITS . What should I do? Insufficient quota. Go to doubaoya.com to recharge and retry.--sync sync tasks are not charged.

Q6: It prompts PROVIDER_FAILED . What should I do? The upstream temporarily failed. The system has automatically issued a refund; just retry directly (retries are safe).