소셜 데이터 (베타)

/

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/tiktok/search" \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  --data-urlencode 'keyword=TikTok'

# 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 — 데이터 소스가 응답하지 않았거나, 데이터 없이 응답했습니다.
  • 503 social_data_unavailable — 이 엔드포인트는 현재 일시 중지 상태이며, 실시간 카탈로그에 paused로 표시됩니다.

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

허용되는 사용

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

플랫폼과 가격

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

엔드포인트

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