API와 SDK로 개발하기
7:50 안내 영상
영상 내레이션은 영어로 제공됩니다.
Toktik Developer API는 종량제 REST API이며, 공식 SDK로 JavaScript/TypeScript용 @toktikhq/sdk-js와 Python용 toktik을 제공합니다. 빠른 시작, 인증, 크레딧부터 시작하고 바로 쓸 수 있는 cURL, JavaScript, Python 예제를 복사하세요.
배울 내용
- 키를 발급하고 첫 인증 요청 보내기
- 스코프, 속도 제한, 크레딧 모델 이해하기
- JavaScript 및 Python SDK 사용하기
- 문서 읽기: 빠른 시작, 엔드포인트, 스코프
진행 방식
Settings에서 키 만들기
앱에서 Settings를 열고 Developer keys로 이동해, 필요한 스코프만 지정한 키를 만드세요(예: 랭킹용 rank:read). 시크릿은 ttk_live_로 시작하며 한 번만 표시되므로 환경 변수에 저장하세요. 키는 데이터 라우트에만 접근할 수 있고, 키 생성은 로그인 상태에서만 가능합니다.
첫 번째 요청 보내기
ttk_live_ 시크릿을 Authorization: Bearer로 전달해 키를 보내세요. 문서의 빠른 시작은 board=hourly, region=VN으로 api.toktikhq.com/v1/rankings/official의 공식 랭킹 보드를 호출합니다. 403은 키에 해당 라우트의 스코프가 없다는 뜻입니다.
제한과 크레딧 안에서 사용하기
각 키에는 플랜별 초당 요청 한도가 있으며 Free의 1부터 Agency의 150까지입니다. 한도를 넘으면 429가 반환되므로 Retry-After만큼 기다린 뒤 다시 시도하세요. 크레딧이 소진되면 402가 반환되며 재시도로는 해결되지 않습니다. GET /v1/usage로 사용량을 확인할 수 있습니다.
공식 SDK 추가하기
JavaScript와 TypeScript는 npm i @toktikhq/sdk-js, Python은 pip install toktik으로 설치하세요. 둘 다 같은 키와 같은 크레딧 지갑으로 같은 v1 REST API를 호출합니다. Docs의 Quickstart와 API Reference 페이지에 모든 엔드포인트, 파라미터, 스코프가 나와 있습니다.
자주 묻는 질문
Toktik API 비용은 얼마인가요?
별도의 API 가격표는 없습니다. 웹 앱과 API는 같은 플랜의 같은 크레딧 지갑을 사용합니다. Toktik의 저장소에서 제공하는 조회는 1크레딧, 내보내기는 2,500크레딧이며, 온디맨드 수집 호출은 더 많이 듭니다.
Toktik API의 속도 제한은 어떻게 되나요?
키당 초당 한도는 Free 1, Starter 5, Pro 20, Scale 60, Agency 150입니다. 일일 할당량도 적용되며 Free의 5,000 요청부터 Agency의 1,200,000 요청까지입니다. 한도를 초과하면 윈도우 상태를 보여주는 헤더와 함께 429가 반환됩니다.
Toktik에는 공식 SDK가 있나요?
네. @toktikhq/sdk-js는 JavaScript와 TypeScript를, toktik 패키지는 Python을 지원합니다. 둘 다 같은 키로 같은 v1 REST API를 호출합니다.
Toktik API의 402와 403은 어떻게 다른가요?
402는 워크스페이스의 크레딧이 소진되었다는 뜻이므로 재시도하지 말고 충전하세요. 403은 키는 유효하지만 필요한 스코프가 없다는 뜻이므로 스코프를 부여하거나 로그인 세션을 사용하세요. 429는 속도 제한이며 잠시 기다린 뒤 다시 시도해도 안전합니다.