TikTok · 인기 동영상 순위

베타

소셜 플랫폼의 공개 데이터를 호출 단위로 과금해 제공합니다. API 키와 잔액은 모델 호출과 같습니다.

미결제 계정은 하루 최대 50회 호출할 수 있습니다. 유료 계정은 일일 호출 수 제한이 없습니다. 매일 00:00 UTC에 초기화됩니다. · HTTP 200과 비어 있지 않은 data를 반환한 호출만 과금합니다. 결과가 비어 있거나, 파라미터가 거부되거나, 업스트림이 실패한 경우에는 과금하지 않습니다.

요청 매개변수

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

이름	유형	필수	예시	설명
`period_end_timestamp`	integer	예	`1794182400`	Ranking period end
`period_dimension`	integer	아니요	`3`	Ranking period: 1 weekly, 3 daily (default), 5 long-period; selects the ranking type for period_end_timestamp, not the last 1/3/5 기본값 `3`
`country_code`	string	아니요	`"US"`	Country code 기본값 `"US"`
`content_label_ids`	string	아니요	`""`	Content label IDs, comma separated 기본값 `""`
`order_by_metric`	integer	아니요	`1`	Order by metric 기본값 `1`
`organic_only`	boolean	아니요	`false`	Organic content only 기본값 `false`
`page`	integer	아니요	`1`	Page number 기본값 `1`
`limit`	integer	아니요	`20`	Items per page, max 100 기본값 `20`

요청 예시

curl --get "https://api.chinaapi.ai/v1/social/tiktok/video-trends" \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  --data-urlencode 'period_end_timestamp=1794182400'

응답 구조

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

{
  "object": "social.result",
  "platform": "tiktok",
  "capability": "video-trends",
  "data": { … }
}

페이지 나누기

페이지 파라미터: page. 페이지마다 별도로 과금되는 호출입니다. 커서 값은 이전 응답에서 받은 그대로 넘기세요.

오류와 과금되지 않는 경우

상태 코드	오류 코드	의미
400	—	파라미터가 알 수 없거나, 중복되었거나, 너무 길거나, 타입이 틀렸거나, 빠진 경우입니다. "하나 이상 필요" 그룹에서 아무것도 주지 않은 경우도 포함됩니다. 어느 경우인지는 오류의 `code`(예: `unknown_parameter`, `missing_parameter`)로 알 수 있습니다.
403	—	이 API 키에는 이 요청을 실행할 권한이 없습니다.
404	`social_data_no_result`	해당 플랫폼과 기능 조합이 없거나, 플랫폼이 이 파라미터로 아무것도 찾지 못했습니다(`social_data_no_result`).
429	`data_api_daily_limit_exceededsocial_data_capacity_reached`	베타의 하루 용량이 소진되어 00:00 UTC에 초기화되기를 기다려야 하거나, 플랫폼이 혼잡한 상태입니다. 후자라면 몇 초 뒤 재시도하면 됩니다. 짧은 간격으로 재시도를 반복하지 마세요. 미결제 계정은 하루 최대 50회 호출할 수 있습니다. 유료 계정은 일일 호출 수 제한이 없습니다. 매일 00:00 UTC에 초기화됩니다.
502	`social_data_no_result`	데이터 소스가 응답하지 않았거나, 데이터 없이 응답했습니다.
503	`social_data_unavailable`	이 엔드포인트는 현재 일시 중지 상태이며, 실시간 카탈로그에 `paused`로 표시됩니다.

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

모든 응답에는 X-Oneapi-Request-Id 헤더가 붙습니다. 지원팀에 문의할 때 함께 보내 주시면 해당 호출을 찾을 수 있습니다.

베타 이용 조건

미결제 계정은 하루 최대 50회 호출할 수 있습니다. 유료 계정은 일일 호출 수 제한이 없습니다. 매일 00:00 UTC에 초기화됩니다. 베타에는 SLA가 없고 플랫폼, 엔드포인트, 가격이 바뀔 수 있습니다.

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

데이터 API 속도 혜택

유료 계정은 초당 10회 요청으로 시작하며 누적 순이용액에 따라 초당 최대 100회까지 자동으로 늘어납니다.

미결제 계정은 하루 최대 50회 호출할 수 있습니다. 유료 계정은 일일 호출 수 제한이 없습니다. 매일 00:00 UTC에 초기화됩니다.

누적 순이용액	초당 요청 수
유료 계정 기본값	10/s
50달러 초과	20/s
500달러 초과	50/s
1500달러 초과	100/s

산정 기준은 데이터 API 정산 금액에서 호출 환불액을 뺀 금액입니다. 충전액과 모델 API 이용액은 포함하지 않습니다.

계정의 모든 API 키가 이 속도를 공유합니다. 동시 실행 수가 아니라 초당 요청 수입니다.

공급자 엔드포인트에는 별도의 용량 제한이 있으며 실제 처리 속도에도 영향을 줍니다.

더 높은 속도가 필요하면 [email protected]로 이메일을 보내 주세요.