Douyin Xingtu APIs - Author Search (V1)

prod-global

GET

/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1

Search for authors using filters.

Parameters

Name	In	Type	Required	Description
token	query	string	Yes	User authentication token.
keyword	query	string	No	Search keyword.
searchType	query	string	No	Search criteria type. Available Values: - NICKNAME: By Nickname - CONTENT: By Content
followerRange	query	string	No	Follower range (e.g., 10-100).
kolPriceType	query	string	No	KOL price type. Available Values: - 视频1_20s: Video 1-20s - 视频21_60s: Video 21-60s - 视频60s以上: Video > 60s - 定制短剧单集: Mini-drama episode - 千次自然播放量: CPM naturally - 短直种草视频: Short-live seeding video - 短直预热视频: Short-live warm-up video - 短直明星种草: Celebrity short-live seeding - 短直明星预热: Celebrity short-live warm-up - 明星视频: Celebrity video - 合集视频: Collection video - 抖音短视频共创_主投稿达人: Douyin short video co-creation - main creator - 抖音短视频共创_参与达人: Douyin short video co-creation - participant
kolPriceRange	query	string	No	KOL price range (e.g., 10000-50000).
contentTag	query	string	No	Content tag filter.

Code Samples

💡 Environment Note

Default samples use https://api.justoneapi.com (prod-global). For users in Mainland China, it is recommended to replace it with http://47.117.133.51:30015 (prod-cn) for better performance. See Environment Guide.

🐚 cURL

# Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
curl -X GET "https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1?token=YOUR_API_KEY"

🤖 AI Prompt

I want to use the "Author Search (V1)" API from Just One API.
API Endpoint: https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1
HTTP Method: GET
Authentication: Append "?token=YOUR_API_KEY" to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/douyin-xingtu-apis/author-search-v1-en.json

Parameters:
- token (query): User authentication token. (Required)
- keyword (query): Search keyword.
- searchType (query): Search criteria type.

Available Values:
- `NICKNAME`: By Nickname
- `CONTENT`: By Content
- followerRange (query): Follower range (e.g., 10-100).
- kolPriceType (query): KOL price type.

Available Values:
- `视频1_20s`: Video 1-20s
- `视频21_60s`: Video 21-60s
- `视频60s以上`: Video > 60s
- `定制短剧单集`: Mini-drama episode
- `千次自然播放量`: CPM naturally
- `短直种草视频`: Short-live seeding video
- `短直预热视频`: Short-live warm-up video
- `短直明星种草`: Celebrity short-live seeding
- `短直明星预热`: Celebrity short-live warm-up
- `明星视频`: Celebrity video
- `合集视频`: Collection video
- `抖音短视频共创_主投稿达人`: Douyin short video co-creation - main creator
- `抖音短视频共创_参与达人`: Douyin short video co-creation - participant
- kolPriceRange (query): KOL price range (e.g., 10000-50000).
- contentTag (query): Content tag filter.

Return format: JSON

Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set request timeout to at least 60 seconds.
3. Business Code Reference:
   - 0: Success
   - 100: Invalid or Inactive Token
   - 301: Collection Failed. Please Retry.
   - 302: Rate Limit Exceeded
   - 303: Daily Quota Exceeded
   - 400: Invalid Parameters
   - 500: Internal Server Error
   - 600: Permission Denied
   - 601: Insufficient Balance

Please help me write a script in my preferred programming language to call this API and handle the response.

🐍 Python

# Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
import requests

url = "https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1?token=YOUR_API_KEY"
response = requests.get(url)
print(response.json())

🌐 JavaScript

// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
const response = await fetch("https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1?token=YOUR_API_KEY", {
  method: "GET"
});
const data = await response.json();
console.log(data);

☕ Java

// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1?token=YOUR_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

🐹 Go

// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	client := &http.Client{}
	url := "https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1?token=YOUR_API_KEY"
	req, _ := http.NewRequest("GET", url, nil)
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

🐘 PHP

// Tip: For Mainland China, replace https://api.justoneapi.com with http://47.117.133.51:30015
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.justoneapi.com/api/douyin-xingtu/gw/api/gsearch/search_for_author_square/v1?token=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
curl_close($ch);
echo $response;

[OpenAPI Definition (JSON)]

Responses

{
  "code": 0,
  "data": {
    "authors": [
      {
        "attribute_datas": {
          "author_avatar_frame_icon": "0",
          "author_ecom_level": "L4",
          "author_level_game": "Lv1",
          "author_level_other": "Lv1",
          "author_status": "1",
          "author_thin_mid_word_association_index": "{\"清爽\":0.003}",
          "author_type": "3",
          "avatar_uri": "https://p3.douyinpic.com/aweme/1080x1080/aweme-avatar/tos-cn-avt-0015_a4391e9fc88a3ed36b0448661f82bc...",
          "brand_boost_vv": "0",
          "city": "",
          "content_theme_labels_180d": "[\"异国旅行\",\"海外旅行\",\"美食探店\",\"家庭生活记录\",\"环球影城之旅\",\"游乐园游玩\",\"三角洲新赛季\",\"个人模仿秀\",\"游戏赛事指南\",\"游戏体验展示\"]",
          "core_user_id": "84990209480",
          "e_commerce_enable": "1",
          "ecom_avg_order_value_30d_range": "50-200",
          "ecom_gmv_30d_range": ">100w",
          "ecom_gpm_30d_range": "1000-3000",
          "ecom_score": "89",
          "ecom_video_product_num_30d": "0",
          "ecom_watch_pv_30d": "1.3",
          "expected_cpa3_level": "4",
          "expected_natural_play_num": "4532776",
          "expected_play_num": "3535761",
          "fans_increment_rate_within_15d": "-0.00033109494533874244",
          "fans_increment_within_15d": "-21105",
          "fans_increment_within_30d": "8352287.33",
          "follower": "63747138",
          "game_type": "{\"\\u5c04\\u51fb\": 1.0}",
          "gender": "1",
          "grade": "0",
          "id": "6855230644880949262",
          "interact_rate_within_30d": "0.033",
          "is_black_horse_author": "false",
          "is_cocreate_author": "false",
          "is_cpm_project_author": "0",
          "is_excellenct_author": "0",
          "is_short_drama": "0",
          "last_10_items": "[{\"comment_cnt\":\"1138\",\"is_high_quality_item\":\"0\",\"item_create_time\":\"1772962802\",\"item_id\":\"7614816...",
          "link_convert_index": "99.48",
          "link_convert_index_by_industry": "99.48",
          "link_i_cnt_by_industry": "29863242",
          "link_k_cnt_by_industry": "74458",
          "link_l_cnt_by_industry": "42264967",
          "link_link_cnt_by_industry": "96324334",
          "link_n_cnt_by_industry": "24121667",
          "link_recommend_index_by_industry": "94.3",
          "link_shopping_index": "94.3",
          "link_spread_index": "94.28",
          "link_spread_index_by_industry": "94.28",
          "link_star_index": "86.28",
          "link_star_index_by_industry": "86.28",
          "link_user_type_by_industry": "2",
          "local_lower_threshold_author": "false",
          "nick_name": "陈赫",
          "pic_brand_boost": "false",
          "pic_brand_boost_vv": "0",
          "pic_expected_play_num": "566107",
          "play_over_rate_within_30d": "0.2841",
          "price_1_20": "270000",
          "price_20_60": "337500",
          "promotion_prospective_1_20_cpm": "58.89",
          "promotion_prospective_20_60_cpm": "73.62",
          "promotion_prospective_vv": "4584657",
          "prospective_1_20_cpm": "76.3626",
          "prospective_20_60_cpm": "95.4533",
          "province": "上海市",
          "search_after_view_index_by_industry": "98.99",
          "sn_expected_play_num": "3535761",
          "sn_interact_rate_within_30d": "0.033",
          "sn_play_over_rate_within_30d": "0.2841",
          "sn_prospective_1_20_cpe": "3.1892",
          "sn_prospective_1_20_cpm": "76.3626",
          "sn_prospective_20_60_cpe": "3.9865",
          "sn_prospective_20_60_cpm": "95.4533",
          "star_excellent_author": "0",
          "star_index": "66.53827749888086",
          "star_qianchuan_high_potential": "0",
          "star_whispers_author": "0",
          "tags_relation": "{\"影视娱乐\":[\"明星资讯\"]}",
          "video_brand_boost": "false",
          "video_brand_boost_vv": "0"
        },
        "extra_data": {
          "content_query_from_word": "",
          "content_query_score": 0,
          "debug_info": "",
          "demander_behavior": {
            "added_author_list": false,
            "cooperated": false,
            "viewd_author_page": false
          },
          "recall_from": [
            "1_0"
          ],
          "recall_return_infos": {},
          "recommend_types": []
        },
        "items": [
          {
            "item_id": "7604417718469233650",
            "video_tag": 3,
            "vv": 67750569
          }
        ],
        "star_id": "6855230644880949262",
        "task_infos": [
          {
            "online_status": 2,
            "platform_source": 1,
            "price_infos": [
              {
                "end_time": "2145916800",
                "platform_source": 1,
                "price": 337500,
                "price_extra_info": {},
                "start_time": "1757062015",
                "task_category": 1,
                "video_type": 2,
                "video_type_status": 1
              }
            ],
            "task_category": 1,
            "task_status": 1
          }
        ]
      }
    ],
    "base_resp": {
      "status_code": 0,
      "status_message": ""
    },
    "extra_data": {
      "intent_score": 0.6370054483413696,
      "is_cpm_project_search": false,
      "is_intent_consistent": true,
      "search_author_count": 0,
      "search_item_count": 0,
      "search_session_id": "7615252989129637942"
    },
    "pagination": {
      "has_more": true,
      "limit": 20,
      "page": 1,
      "total_count": 10000
    }
  }
}

💡 Note: For list data, the example shows only 1-2 items for simplicity. The actual count depends on the API response.