소셜 데이터 (베타)

/

GET /v1/social/{platform}/{capability}는 Douyin, Xiaohongshu, TikTok, YouTube 등 소셜 플랫폼의 공개 데이터를 반환하며, 모델 호출과 같은 API 키와 잔액을 사용합니다. 요금은 플랫폼과 기능마다 성공한 호출 1회 단위로 매겨지고, data는 플랫폼의 원본 응답 그대로입니다 — 필드는 플랫폼 간에 통일되어 있지 않습니다.

GET /v1/social/{platform}/{capability} 
curl --get "https://api.chinaapi.ai/v1/social/bilibili/search" \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  --data-urlencode 'keyword=Python'

# HTTP 200
# {"object": "social.result", "platform": "tiktok", "capability": "search", "data": {...}}
베타: 유료 계정 전용 호출하기 전에 첫 충전을 완료하세요. 체험 크레딧은 이 엔드포인트에 쓸 수 없으며, 한 번도 충전하지 않은 계정은 HTTP 403 model_requires_topup을 받습니다. 베타에는 SLA가 없고 플랫폼, 엔드포인트, 가격이 바뀔 수 있습니다.

인증과 과금

다른 모델 호출과 마찬가지로 ChinaAPI 키를 bearer 토큰으로 https://api.chinaapi.ai에 보냅니다. 호출은 HTTP 200과 함께 데이터를 반환했을 때에만, 해당 엔드포인트에 표시된 가격으로 한 번 과금됩니다. 결과가 비어 있거나, 파라미터가 거부되었거나, 업스트림이 실패하면 비용이 들지 않습니다. 페이지를 하나 가져올 때마다 별도의 호출입니다. 사용 로그에는 각 호출이 엔드포인트와 함께 표시된 이름(예: social-douyin-search)으로 기록됩니다.

응답과 오류

성공한 응답은 플랫폼의 데이터를 작은 래퍼로 감싸서 돌려줍니다. data 안의 모든 것(필드 이름, 페이지네이션 커서, ID)은 플랫폼 고유의 것이므로, 커서는 받은 그대로 다시 보내세요.

{
  "object": "social.result",
  "platform": "douyin",
  "capability": "search",
  "data": { "...": "the platform's own fields" }
}
  • 400 — 파라미터가 알 수 없거나, 중복되었거나, 너무 길거나, 타입이 틀렸거나, 빠진 경우입니다. "하나 이상 필요" 그룹에서 아무것도 주지 않은 경우도 포함됩니다. 어느 경우인지는 오류의 code(예: unknown_parameter, missing_parameter)로 알 수 있습니다.
  • 403 model_requires_topup — 계정이 첫 충전을 완료하지 않았습니다.
  • 404 — 해당 플랫폼과 기능 조합이 없거나, 플랫폼이 이 파라미터로 아무것도 찾지 못했습니다(social_data_no_result).
  • 429 social_data_capacity_reached — 베타의 하루 용량이 소진되어 00:00 UTC에 초기화되기를 기다려야 하거나, 플랫폼이 혼잡한 상태입니다. 후자라면 몇 초 뒤 재시도하면 됩니다. 짧은 간격으로 재시도를 반복하지 마세요.
  • 502 social_data_no_result — 데이터 소스가 응답하지 않았거나, 데이터 없이 응답했습니다.
  • 503 social_data_unavailable — 이 엔드포인트는 현재 일시 중지 상태이며, 실시간 카탈로그에 paused로 표시됩니다.

이 응답들은 모두 과금되지 않습니다.

LinkedIn asynchronous tasks

The post-async, user-async and company-async capabilities use POST, query parameters and an empty body. Supply an Idempotency-Key (8–128 characters) unique to your intended operation. Reusing the same key and parameters returns the original submission without another charge; changing parameters under that key returns HTTP 409. A lost response is retried with the same key.

curl --get -X POST "https://api.chinaapi.ai/v1/social/linkedin/company-async" \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Idempotency-Key: company-research-20261029-001" \
  --data-urlencode 'url=https://www.linkedin.com/company/microsoft/'

# HTTP 202 returns a ChinaAPI task id and Location.
curl "https://api.chinaapi.ai/v1/social-tasks/TASK_ID" \
  -H "Authorization: Bearer $CHINAAPI_KEY"

Creation reserves the catalog price. A task with usable records keeps that charge; failure, empty results or timeout refund the reservation. Status and result reads are free, require the same account, and do not create another task. Poll no faster than every five seconds. Results are available for 30 days; do not submit another paid task just to read the same result. submission_pending means the submission outcome is uncertain: keep the same key and contact support if it persists.

These asynchronous capabilities are available through REST. The data MCP fetch tool lists synchronous capabilities only.

Xiaohongshu creator hot topics

GET /v1/social/xiaohongshu/creator-hot-topics returns the creator center’s hot inspiration feed. This is a separate capability, not a platform-wide trending ranking; the old trending endpoint remains unavailable. The live catalog lists its per-call price.

Leave cursor empty on the first request. Pass the response’s data.data.cursor unchanged to fetch the next page; items are in data.data.items. Stop when data.data.end_flag is true, a cursor repeats, or a page has no new items. Each successful nonempty page is billed separately. Empty results and business errors are not charged.

Telegram public channels

Telegram user returns a public channel profile, post returns one channel post, and user-posts returns channel posts. These endpoints do not retrieve personal account profiles or private chats. Pass channel=durov; a post also needs its post_id. Comments remain unavailable.

For user-posts, limit is 1–100 (upstream default 20). Fetch older posts with the preceding response's data.pagination.before_cursor as before; fetch newer posts with data.pagination.after_cursor as after. Choose one direction per request. Read posts from data.messages, deduplicate by post ID, and stop on an empty page, repeated cursor, no new IDs or your page/spending limit. has_more_before=false ends backward collection. Each nonempty successful page is billed separately; unavailable previews and empty results are not charged. Media links can expire.

Search implementation changes

TikTok search uses the App V3 implementation with keyword, offset, count, sort_type and publish_time. Start at offset 0; the former Web search_id is not supported. Returned data retains App V3 fields. Threads search returns top results and supports no pagination; results can vary by query and retrieval time. These path changes keep the previous per-call prices.

Pagination and bounded collection

Douyin comments and comment replies use the App V3 cursor contract. Start with cursor=0 and count=20; only count 20 is supported. Comment replies require both item_id (video ID) and comment_id (parent comment ID). Pass the returned cursor unchanged within the same capability. Old Web cursors cannot be reused.

Pages can overlap even when the cursor advances. Deduplicate by cid, stop when has_more is false, when a cursor repeats, or when no new IDs arrive; set a maximum page count and a spending limit. Each successful page is separately billed, including overlapping items. An empty page returns an uncharged no-result error and should end collection.

Threads comments and top search currently support the first page only. Sending a nonempty end_cursor is rejected before billing. Do not interpret a first-page response as a complete comment history. For every platform, use only the pagination parameters advertised in the live catalog.

허용되는 사용

각 플랫폼의 약관과 사용자에게 적용되는 데이터 보호 규정을 따르세요. 이 API로 개인의 프로필을 구축하지 마세요. 로그인, 연락처 추출, 참여 지표 조작, 비공개 또는 유료 콘텐츠 접근은 이번 베타의 범위가 아닙니다.

플랫폼과 가격

성공한 호출 1회당 USD입니다. 각 가격은 아래의 해당 엔드포인트로 연결되며, 대시는 그 플랫폼이 해당 기능을 제공하지 않는다는 뜻입니다. 지금 판매 중인 항목은 일시 중지된 엔드포인트를 포함해 실시간 카탈로그 — GET https://dash.chinaapi.ai/api/social/catalog, 키 불필요 — 가 기준입니다.

엔드포인트

파라미터는 플랫폼 고유의 이름으로 쿼리 문자열에 넣습니다. 예시는 카탈로그에서 가져온 것이니, 식별자는 가져오려는 콘텐츠의 것으로 바꾸세요.