Blog/Developer Tools/

Douyin Public Data API | SandBase

Read public Douyin billboards, search, videos, and comments with one REST API. No Douyin login, no SDK — one SandBase key, built for agents.

By Sophie Lin
Dark cinematic render of Douyin billboard, search, and video data flowing through one API conduit into an agent core

Douyin is the Chinese short-video engine that sets trends for a billion viewers — ranked billboards, brand hot searches, video search, and comment streams that map directly onto trend research, brand monitoring, and content analytics. Getting at it programmatically usually means reverse-engineering the app, rotating device tokens, and rebuilding a scraper every time the app changes.

The SandBase Douyin public data API removes that setup tax. It reads public Douyin billboards, search results, videos, and comments through plain REST endpoints — one SandBase API key, no Douyin login and no SDK. The endpoint API reference is the source of truth for each parameter and for the response envelope (id/status/model/outputs[0].data); the business-payload field names shown below are an illustrative shape, not a guaranteed schema, so confirm them against a live response.

This is not Douyin’s official open platform. Use Douyin’s official channels when you need authenticated member actions or a licensed data agreement. Use SandBase when your workflow needs public, read-only data for research and monitoring. Ready to try it? Get a SandBase API key and browse the Douyin endpoints.

Key takeaway

  • One API reads public Douyin billboards, brand hot searches, search results, videos, and comments.
  • The Model API endpoints in this guide are called with POST /v1/api/douyin/<path> — pass only that endpoint’s params, no SDK, one SANDBASE_API_KEY.
  • Endpoints key off natural identifiers: an aweme_id for a video, a keyword for search, or a video url.
  • It returns public, read-only data only. There is no posting, no platform login or OAuth on your side, and no private or account-authorized data; authenticate with a SandBase API key.

Which Douyin API do you need?

Your needChooseWhy
Post, act as a member, or use account-authorized dataDouyin’s official channelsMember and account operations run through Douyin directly.
Read public billboards, search, videos, or commentsSandBase Douyin public-data APIPlain REST, one SandBase key, structured JSON for read-only workflows.
Creator-console or account-authorized analyticsNeither public workflowConsole data that requires a login is out of scope for this public-data guide.

What you can get from the Douyin API

The catalog spans several surfaces (billboards, search, web, and app reads). Grouped by job:

  • Billboards — ranked lists such as top-liked videos and brand hot searches.
  • Search — video, image, music, and challenge search by keyword.
  • Videos — resolve an aweme_id from a URL, then read video and comment data.
  • Comments — video comments by aweme_id.

Check each endpoint’s live API reference for the exact surface and parameters before you build; availability differs by endpoint, and some creator-console endpoints require authentication that is out of scope here.

SandBase Douyin API page: description, capability tags, and the endpoint list The Douyin API page on SandBase — a tagged overview and the endpoint list, each with its path.

What Douyin provides vs. what SandBase adds

Public data comes from Douyin. SandBase does not own or operate Douyin; it provides a uniform API layer for eligible public-data workflows. Each capability becomes one stable endpoint, auth collapses to a single key, and responses come back as predictable JSON — so an agent can chain “read a billboard → search a keyword → read a video’s comments” along one convention instead of maintaining a scraper.

Quick start: your first call

SandBase exposes more than one API surface. The catalog may show GET paths under /apis/v1/...; this guide uses the vendor-qualified Model API path on each endpoint’s API reference. Do not swap the HTTP method or URL — follow the reference for the endpoint you choose.

Read the top-liked video billboard:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/douyin/billboard/hot-total-high-like-list",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "Douyin request did not complete"))

# The reference only guarantees the envelope; business fields vary by endpoint — confirm against a live response.
data = body["outputs"][0]["data"].get("data", {})
items = data.get("objs", [])
for it in items[:5]:
    print(it.get("item_title"), it.get("fans_cnt"))
curl -X POST https://api.sandbase.ai/v1/api/douyin/billboard/hot-total-high-like-list \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Every response uses the same envelope: an id, a status, the model name, and an outputs array whose single item carries the payload under data. Branch on status before reading outputs[0].data, and check each endpoint’s reference for its run mode. Douyin endpoints often wrap their payload in an upstream { code, data, message } object, so the useful list sits under data.data.objs. The block below is an illustrative response shape — the field names are not a guaranteed schema, so confirm them against a live response, since payloads vary and change over time:

{
  "id": "f243b2d6-b103-4ed3-b372-28f2b150cbab",
  "status": "completed",
  "model": "douyin/billboard/hot-total-high-like-list",
  "outputs": [
    {
      "data": {
        "code": 0,
        "data": {
          "objs": [
            { "item_id": "…", "item_title": "…", "fans_cnt": 0, "item_url": "…" }
          ]
        }
      }
    }
  ]
}

A failed or timeout run carries error and never outputs. Response shapes differ by endpoint — inspect one real response and map the exact path per endpoint.

SandBase API reference for a Douyin endpoint, showing the vendor-qualified URL and the response schema The endpoint API reference is the source of truth for each parameter name and response path.

Capability map

Capability clusterRepresentative endpointTypical use
Video billboarddouyin/billboard/hot-total-high-like-listTop-content trend monitoring
Brand hot searchdouyin/app-v3/brand-hot-search-listBrand and category tracking
Searchdouyin/search/image-search-v3Keyword content discovery
Video resolvedouyin/web/aweme-idTurn a video URL into an aweme_id
Video commentsdouyin/app-v3/video-commentsEngagement and sentiment inputs

Paging differs by endpoint — several endpoints accept a request parameter such as a cursor. Read each endpoint’s schema.

SandBase Douyin endpoint list showing billboard, search, video, and comment endpoints with their paths A slice of the Douyin endpoint list across the billboard, search, web, and app surfaces.

Chaining calls in an agent workflow

Because every endpoint shares the same auth and the same response envelope, an agent can walk from a billboard to a video’s comments without special-casing each surface. A common content-research pattern looks like this:

  1. Read a billboard. Call douyin/billboard/hot-total-high-like-list to get top-liked videos, then pick the ones you care about.
  2. Resolve a video. Call douyin/web/aweme-id with a video url to get its aweme_id.
  3. Read the comments. Call douyin/app-v3/video-comments with the aweme_id for engagement and sentiment inputs.

Each step returns the same { id, status, model, outputs } shape, so your agent branches on status once and reuses the same JSON-reading code across every step.

Common use cases

Douyin billboard API for trend monitoring

Poll douyin/billboard/hot-total-high-like-list on a schedule to track top-content — each item carries a title and creator signals. Input: none. Output: a ranked list of videos. Endpoint: hot-total-high-like-list.

Douyin brand API for brand tracking

Read douyin/app-v3/brand-hot-search-list for brand hot-search categories. Input: none. Output: brand hot-search categories. Endpoint: brand-hot-search-list.

Douyin search API for content discovery

Run douyin/search/image-search-v3 with a keyword to survey content around a topic. Input: a keyword. Output: matching results. Endpoint: image-search-v3.

Why run this at the API layer

You could point a headless browser at Douyin and parse the app’s payloads, but that path is fragile: the app changes, tokens rotate, and you maintain a scraper instead of shipping features. Reading through one uniform API means your code depends on named JSON fields and a single response envelope rather than an app internal. Auth is one key, and because every endpoint returns the same { id, status, model, outputs } shape, retries, logging, and error handling live in one helper you write once and reuse everywhere.

That uniformity is what makes the workflow composable for an agent. Swap one billboard for another, swap one keyword for another, and the code path is identical. Add a fourth read — a video’s statistics, say — and it slots in behind the same status-checking helper. The practical payoff is that your time goes to what the data means for your research, not to keeping a scraper alive against a moving target. When you need more than single reads, check the live listing for the endpoint that fits and confirm its parameters before wiring it in.

Limitations and boundaries

  • Public, read-only data only. No posting, following, or private/account-only data. Creator-console endpoints that require a login are out of scope.
  • Rate and volume. Treat responses as best-effort reads; as a client-side resilience measure, retry with backoff on transient errors such as HTTP 429.
  • Parameters and shapes follow the upstream surface. Identifiers vary (aweme_id, keyword, video url); payloads often nest under an upstream data object; paging is a per-endpoint request parameter. Inspect a real response and read the schema first.
  • Verify endpoints against the live reference. Availability and fields can change; confirm before building on a specific endpoint.
  • This is not an official Douyin partnership. SandBase provides uniform access to public data; respect Douyin’s terms and applicable rules for your use case.

FAQ

Do I need a Douyin developer app or login? No. You authenticate to SandBase with your SANDBASE_API_KEY. These read endpoints do not require a Douyin account or OAuth on your side.

What identifies a video? A video’s aweme_id. Use web/aweme-id to turn a video URL into an aweme_id, then pass it to the video and comment endpoints. Search takes a keyword.

Why is the data nested under data.data? Douyin endpoints often pass through the upstream { code, data, message } envelope, so the useful payload sits under data.data. Read each endpoint’s schema for the exact path.

Can I read creator-console analytics? Not through the public-data workflow. Endpoints that require an account login are out of scope; this guide covers public, read-only reads.

Start with a billboard

Create a SandBase API key, call hot-total-high-like-list, and inspect the returned schema before you expand to search, videos, or comments. When you are ready: