Douyin Xingtu API: Find Candidates or Read a Known Profile

Make one Xingtu search or known-kolId request with strict status and identity checks; keep API costs, candidate prices and historical evaluation evidence separate.

Conceptual Xingtu creator cards with audience, performance and rate-card symbols

A creator-search result is a candidate, not a confirmed booking or a campaign recommendation. If you are starting a Douyin Xingtu integration, first choose between searching a keyword and reading one already selected Xingtu kolId. That distinction keeps a useful first request from expanding into an expensive chain of audience, performance and pricing calls before identity or budget is settled.

This November 8, 2026 repair checks current public contracts and replays saved responses offline. It makes no new business request. The October 1 three-brand experiment remains later in this article as dated evidence, with its original observations and code archive. New search/profile references do not come from that experiment and do not prove a newly executed discovery-to-profile chain.

Key takeaway

  • Search takes a keyword and returns candidates under authors; known-ID base info is a separate flat profile with an exact matching string id.
  • Current profile inputs are string kolId and platformChannel; _1 means Douyin Video and _10 means Douyin Live. This example selects only _1.
  • Require completed outputs[0].data and strict integer base_resp.status_code: 0; missing status is an error.
  • Both selected endpoints currently list $0.02 per call without a free_quota entry. Creator task prices are separate data, not the API fee or a confirmed quote.

The original cover’s three profile cards, audience chart, rising bars and rate-card symbol are conceptual. They do not measure a creator’s suitability or promise that this revision executed a commercial evaluation.

Choose one Xingtu API task

Starting informationEndpointSelected body
A topic to searchSearch Xingtu candidates{"keyword":"人工智能"}
A deliberately selected Xingtu IDRead base info{"kolId":"7038603512770461703","platformChannel":"_1"}

The search example uses the schema keyword for artificial intelligence. The complete saved search instead used example. Do not select its first candidate automatically. A star_id is described as a Xingtu creator identifier usable as kolId, but a display name, Douyin UID, sec_user_id, unique_id or URL is not an interchangeable input. A profile request is another deliberate selection and charge.

Optional search contentTag is a string; followerRange is also a string. Its documented example 10-100 means a 100,000–1,000,000-follower bracket, not an instruction to multiply returned follower values by 10,000. No page, limit, cursor or offset input is declared. Returned pagination metadata does not create an undocumented next-page request. The short example omits optional filters rather than guessing tag identifiers.

The base-info schema now explicitly lists _1 and _10. The old experiment’s successful string 1 test is only historical; do not use it to override the current underscore-prefixed values. A returned numeric platform_channel: [1,10] is likewise different from the request contract. No new live-channel request was performed.

Setup and cost before execution

Already have a key? Reuse the local SANDBASE_API_KEY or existing secret store and install requests if necessary. An already connected agent needs only your selected task and keyword or ID, not another credential. For a new project, give it the setup skill and Markdown quickstart, then ask it to prepare and test one request before execution.

A useful instruction is: “Use my local key to implement one Xingtu candidate search for this keyword. Return the raw candidate identifiers and unknown values, then stop. Do not select a person, fetch a quote, resolve IDs, retrieve contacts, page, or schedule calls.” For known-ID research, choose a single base-info read instead. Never paste a key into the prompt or print it for debugging.

The November 8 inspect lists $0.02 per selected endpoint and includes no free_quota for either. Do not assume an organization’s 100 eligible daily API calls cover these routes. One selected request lists at $0.02; two deliberate requests at $0.04 before any independently verified adjustment. This access price is separate from task prices inside the response. Currency, unit, tax and settlement meaning for those creator-price fields are not newly established here.

One request with explicit failure handling

Use the Model API POST /v1/api/<model> route, not catalog GET navigation. This helper returns the unchanged business object after validating its selected structure. It has no fallback to top-level output, no missing-status-as-zero rule and no automatic retry.

Python
import os
import re
import requests

API = "https://api.sandbase.ai/v1/api/douyin/xingtu"


def first_request(task, value):
    if task == "search":
        if not isinstance(value, str) or not value.strip():
            raise ValueError("Provide a selected keyword")
        route, params = "search-kol-v2", {"keyword": value}
    elif task == "profile":
        if not isinstance(value, str) or not re.fullmatch(r"[1-9][0-9]*", value):
            raise ValueError("Provide the selected kolId as a decimal string")
        route = "kol-base-info-v1"
        params = {"kolId": value, "platformChannel": "_1"}
    else:
        raise ValueError("Choose search or profile")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise ValueError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(
            f"{API}/{route}",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=params, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"SandBase HTTP {response.status_code}; request stopped")
        body = response.json()
    except requests.RequestException:
        raise RuntimeError("Network request failed; no automatic retry made") from None
    except ValueError:
        raise RuntimeError("SandBase returned invalid JSON") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase request did not complete")
    outputs = body.get("outputs")
    if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
        raise RuntimeError("Missing documented outputs[0]")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing documented outputs[0].data object")
    status = payload.get("base_resp")
    if (not isinstance(status, dict)
            or type(status.get("status_code")) is not int or status["status_code"] != 0):
        raise RuntimeError("Xingtu business status is not integer zero")
    if task == "search":
        authors = payload.get("authors")
        if not isinstance(authors, list) or any(not isinstance(a, dict) for a in authors):
            raise RuntimeError("Missing or malformed authors array")
        for author in authors:
            if (not isinstance(author.get("star_id"), str)
                    or not re.fullmatch(r"[1-9][0-9]*", author["star_id"])
                    or not isinstance(author.get("attribute_datas"), dict)):
                raise RuntimeError("Missing candidate identity or attribute object")
    elif not isinstance(payload.get("id"), str) or payload["id"] != value:
        raise RuntimeError("Profile identity does not match the selected kolId")
    return payload


if __name__ == "__main__":
    result = first_request("search", "人工智能")
    print("Returned candidates:", len(result["authors"]))

To choose the profile, replace the two main-block lines with result = first_request("profile", "7038603512770461703") and print("Matched kolId:", result["id"]). Do not append it after search unless you intentionally want both calls. Decimal-string identity checks are conservative local guards; they avoid large-number precision loss, not a promise that every identifier format is supported.

A valid empty authors array is distinct from a missing array or business failure. An empty success message is allowed because the saved search has one. Redirects, HTTP errors, invalid JSON, timeouts, non-completed runs and malformed identities stop without exposing response bodies or secrets. The profile parser requires only its established identity and business status, not a guessed follower count or contactability flag.

Current references: candidates and an unrelated profile

The complete saved search cea216f6-ecfc-4299-8a6b-62320dca7d07, created August 20, 2026 at 09:45:41.219 UTC, used keyword example. It contains two authors, with pagination page 1/limit 20/total_count 2/has_more false. Here is an exact projection of the first candidate’s attribute object:

JSON
{
  "id": "6629665048593694723",
  "core_user_id": "88710789301",
  "follower": "63858"
}

That candidate’s star_id matches the attribute ID; core_user_id has another role. Its items is empty, while one task contains two numeric zero prices. Neither zero proves free cooperation or an actual offer. The second candidate has follower string 11148, one item and empty task_infos; missing tasks do not establish unavailability or no fees.

Both authors omit the README’s assign_task_price_list and assign_cpm_suggest_price. Their last_10_items values are unresolved capture references, $1d and $1e, not usable video arrays. Do not evaluate them, fetch them or invent decoded clips. Attribute values can be strings, including flags and numbers; generic truthiness would treat string "0" as true. Preserve the raw types and do not turn missing counts into zero.

The search README is a different artificial-intelligence reference with one displayed author, limit 20, total_count 100 and has_more true. Its populated price fields and trimmed row do not supersede the complete two-author capture or prove a successful continuation.

A separate pet-content profile, dea68eaf-4e63-4305-8657-b82f484796fe, was saved October 7, 2026 at 17:37:17.241 UTC using ID 7038603512770461703 and _1. It is not a selected result from the saved search. Selected flat fields are:

JSON
{
  "id": "7038603512770461703",
  "follower": 886798,
  "avg_play": 0,
  "platform_channel": [
    1,
    10
  ],
  "has_phone": true,
  "is_online": true
}

The integer follower count is a different source type from search’s strings. avg_play: 0 does not establish that its videos had no views. No mcn_id is present, so MCN membership stays unknown rather than becoming false. Online/phone flags do not prove current availability, responsiveness, permission to contact or an accessible phone number. Do not extract contacts or QR material into shared reports.

Tags, second-level tags and opened task categories can be JSON-encoded strings, while content themes are an actual array. Keep raw values; any later decoder must target known fields, handle invalid JSON and avoid recursively decoding capture references. Record creation/modification strings are not your observation time or verified account age. The shortened profile README omits identity fields; the strict helper correctly rejects that fragment as incomplete, without adding a fabricated ID.

Historical October 1 experiment, preserved separately

The following records belong to the original October 1, 2026 experiment, previously edited October 24. None of its resolver, audience, performance, service-price, cost or daily-follower sibling routes was revalidated in this repair. The archive preserves all twelve original Python blocks, original articles and hashes. It is audit material, not the current executable workflow: the old helper retried, accepted an undocumented envelope and defaulted missing business status to success.

Historical Free Week Douyin catalog, not current Xingtu pricing Historical API Free Week catalog: 262 endpoints, GET paths and a selected general-search panel marked Free. That old promotion/display does not make either current selected Xingtu route quota-eligible; both now inspected routes list $0.02.

The original fans-portrait request encountered an HTTP error saying “upstream error 400: Request failed. Please retry”; its second attempt completed as e5c76e47-6ace-47d8-b2ef-317fef873e74. That observation does not add retries to the new helper.

Account resolution and audience observations

Rishiji’s user search was 2bd433e3-58f2-445c-93e8-9299d9d2071d, and its resolver 44a9f085-3832-4b92-a183-d5259d43e059 produced the original JSON below. Chinese National Geography and Yitiao resolution records were a6517c08-7b7d-4c19-b932-f83f4c578a8c and e2c448b7-33ed-49d9-9864-cebad3305633. Exact nickname matching narrowed those historical candidates; it was not independent identity verification. The old search for Yitiao ranked other creators first, reinforcing why the new example does not auto-select a result.

JSON
{
  "id": "6677767167234015243",
  "core_user_id": "64117131714",
  "nick_name": "日食记",
  "tag": "美食",
  "base_resp": {"status_code": 0, "status_message": "Success"}
}

Historical Xingtu sec_user_id resolver parameter reference Historical sec_user_id-to-kolId resolver reference with an empty generated payload and its old per-call price line. It is outside the two currently checked routes and does not verify a new ID chain.

At the old experiment date, the channel description was incomplete; _1 and string 1 returned the same record. That dated result stays in the history, while today’s base-info schema explicitly documents _1/_10. The original MCN boolean shortcut is also archived: absent mcn_id must not become “no MCN.”

Rishiji fans portrait e5c76e47-6ace-47d8-b2ef-317fef873e74 gave these unchanged rounded descriptions:

JSON
{
  "distributions": [
    {"type_display": "年龄分布", "description": "24到30岁居多,占比30%"},
    {"type_display": "城市等级分布", "description": "一线居多,占比37%"},
    {"type_display": "八大人群分布", "description": "新锐白领居多,占比26%"},
    {"type_display": "性别分布", "description": "男性居多,占比50%"}
  ]
}

The separate fans-distribution record 82bcca0d-4e4b-4b8f-9ca8-75ca62aabdad had 6,169,425 male and 6,155,171 female counts, effectively even despite the rounded “mostly male, 50%” description. Audience portrait 1d0456b8-5e68-48ce-9a45-0aac0f434471 reported ages 18–23 at 32% and Gen Z as the largest segment, whereas followers skewed 24–30/emerging white-collar. These were separate reported audience/follower distributions, not new measurements.

Performance, price and the three-brand table

Rishiji performance c6d7e6f1-8615-406c-a776-98266ecf1111 reported about 1.79 million play median and 386,000 for the enrollment summary. The original payload had 15 latest_item_info records and a separate latest_star_item_info collection. Do not relabel all listed videos as organic or infer causal sponsored-content decay. Chinese National Geography c4a11532-3bcb-4fe9-a4f7-e448172bb999 had empty summary objects but retained video lists; the old computed median was a separate fallback, not a zero summary.

Historical Xingtu video-performance parameter reference Historical video-performance reference: required kolId/onlyAssign, incomplete value description, enterprise-account note and old price line. Those details and its empty generated response do not establish today’s sibling availability or performance outcomes.

Rishiji service-price record 8bc1807b-f27a-4cd6-883a-1d66b8ac5b3d contained the unchanged excerpt below. The old filtering used enabled task_category 1 video services; other categories included token-price add-ons and an unpriced natural-play settlement item. Those observations are not a current quotation.

JSON
{
  "industry_tags": ["食品饮料-水饮冲调", "3C及电器-大家电", "母婴宠物-宠物生活"],
  "price_info": [
    {"desc": "植入视频", "price": 180000, "settlement_desc": "固定价格", "task_category": 1, "enable": true},
    {"desc": "定制视频", "price": 300000, "settlement_desc": "固定价格", "task_category": 1, "enable": true}
  ]
}

Cost record be7df1c1-692c-427d-9aa9-7ccbd7d26028 supplied expected views and 21_60/60 tiers. The author historically reproduced cpm_21_60 for all three accounts by dividing the placement price by expected views and multiplying by 100,000, inferring fen per 1,000 expected views and a 21–60-second tier. The 60-second/custom-price match held for two accounts, not Rishiji. Those were explicitly dataset-specific inferences, not current authoritative units, currency conversions or a new pricing formula.

Historical Xingtu service-price parameter reference Historical service-price reference with kolId/platformChannel, an incomplete channel description, enterprise-account wording and an old price line. This sibling was not rechecked; the current base-info channel documentation is separate.

The original evaluate workflow completed 21 calls, seven per creator, plus one retried call. This count did not include every extra distribution, audience, daily-follower and v2 experiment mentioned here. Its rounded table is retained:

AccountFollowersRecent play medianIntegrated-video priceExpected viewsFans skew
Rishiji (food)~12.5M~4.1M (15 videos)~¥180k~3.1M24–30, emerging white-collar
Chinese National Geography (nature/science)~5.6M~0.78M~¥8k~0.29M31–40, emerging white-collar
Yitiao (lifestyle/culture)~6.7M~0.30M~¥153k~0.31M31–40, emerging white-collar

The recent-play column used 15 listed videos per account. Its Rishiji value around 4.1M differed from the roughly 1.79M summary because the summary window and method were unspecified. Chinese National Geography had the lowest calculated cost per expected view in that historical comparison; Rishiji had the largest reported plays/expected views, not verified unique reach. Yitiao’s expected views were roughly one tenth of Rishiji’s at a similar listed price. Content themes such as home renovation/home living remained contextual labels, not evidence of campaign fit or guaranteed model recommendations.

Additional historical checks

Daily-follower record f67341bd-80a0-4387-90a5-928d54f669e3 covered September 1–28, 2026: 28 fans_cnt points from about 12.59M to 12.55M. Separately, v2 base, distribution, spread and cost requests completed as 8cd17f09-cadc-487c-b34d-8a4cf3245497, 82bcca0d-4e4b-4b8f-9ca8-75ca62aabdad, 59c050f8-3b65-4117-a30d-169c2a6136fa and 194b74e9-78f2-4711-9d4e-19bd00b07e51; their historical cost values matched the v1 cost record. This is not an instruction to call all siblings now. The old Xinshixiang search comparison also reported different follower counts between Douyin and Xingtu sources; do not silently mix sources.

FAQ

Is a nickname enough for a commercial evaluation? It is enough to start candidate search, not to establish identity, availability, a final price or campaign suitability. Select and verify the intended identifier before a separate paid profile request.

Can zero task prices be treated as a free offer? No. Preserve zero, missing and empty separately. A confirmed quote requires compatible task, format, time and settlement meaning; current evidence does not supply those guarantees.

Can I use daily free API calls here? Neither currently selected endpoint’s inspect includes free_quota. Budget $0.02 for one selected API request, distinct from any creator-commercial amounts.

For general navigation use the Douyin API hub; for an already selected public creator, see the distinct profile and posts guide. Complete one verifiable read before expanding the commercial research workflow.

For a 2026 pricing comparison of the live SandBase Douyin hub, see Best Douyin API in 2026: Pricing Compared.

Found this useful? Share it