TweetAPI 문서

개발자 친화적인 REST API를 통해 포괄적인 공개 Twitter/X 데이터에 접근하세요.

기본 URL

모든 API 요청은 다음 주소로 보내야 합니다.

https://api.tweetapi.com/tw-v2/

인증

X-API-Key 헤더에 API 키를 포함하세요.

headers: {
  'X-API-Key': 'YOUR_API_KEY'
}

API를 호출하기 전에

응답 형식은 JSON입니다.
요금제 제한은 API 키별로 적용되며, 요청 허용량과 분당 요청 제한이 있습니다.
컬렉션 엔드포인트는 지원되는 경우 커서 기반 페이지네이션을 사용합니다.
게시, 참여, 프로필, DM 및 X Chat 엔드포인트에는 TweetAPI 키 외에 계정 작업 권한 필드가 필요할 수 있습니다. 정확한 필수 매개변수는 각 엔드포인트 페이지에서 확인하세요.
429 응답은 요금제 요청 허용량을 모두 사용했거나 분당 제한을 초과했음을 뜻할 수 있습니다. 재시도하기 전에 오류 메시지를 확인하세요. TweetAPI의 tw-v2 엔드포인트는 현재 Retry-After 또는 X-RateLimit-* 헤더를 반환하지 않습니다.

TweetAPI SDK

TweetAPI는 전체 타입 지원, 자동 재시도, 내장 페이지네이션을 제공하는 Python 및 Node.js용 유지관리 SDK를 제공합니다.

Python

pip install tweetapi

from tweetapi import TweetAPI

client = TweetAPI(api_key="YOUR_API_KEY")
user = client.user.get_by_username(username="elonmusk")
print(user["data"]["followerCount"])

GitHub에서 보기

Node.js / TypeScript

npm install tweetapi-node

import TweetAPI from "tweetapi-node";

const client = new TweetAPI({ apiKey: "YOUR_API_KEY" });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data.followerCount);

GitHub에서 보기

개발자 리소스

코드 생성기, API 도구, 계약 기반 통합을 위한 OpenAPI 명세 (영어로 제공되는 페이지)
문서화된 79개 작업을 모두 포함하는 전체 Postman 컬렉션 (영어로 제공되는 페이지)
공개 프로필, 검색, 트윗 상세 요청으로 안전하게 시작할 수 있는 읽기 전용 Postman 빠른 시작 (영어로 제공되는 페이지)

위 리소스는 현재 영어로 제공됩니다.

주요 기능

공개 데이터 접근: 사용자 프로필, 트윗/게시물, 팔로워, 참여 지표
상호작용 기능: 트윗 게시, 좋아요, 리트윗, 북마크, 다이렉트 메시지 관리
검색: 문서화된 쿼리 매개변수로 트윗, 사용자, 미디어 검색
요청 시 최신 데이터 (영어로 제공되는 페이지): 애플리케이션에서 요청할 때 현재 게시물, 프로필, 지표 가져오기(영어 문서)
페이지네이션: 컬렉션 엔드포인트의 커서 기반 페이지네이션
미디어 지원: 이미지, 동영상, GIF 완전 지원

사용 가능한 엔드포인트

사용자 엔드포인트

사용자 이름으로 사용자 조회
ID로 사용자 조회
여러 ID로 사용자 일괄 조회
팔로워 및 팔로잉 목록
사용자 트윗 및 답글
구독 정보

트윗 엔드포인트

트윗 상세 및 대화 스레드
인용 트윗 및 리트윗
트윗 번역
참여 지표

상호작용 엔드포인트

게시물 작성, 답글, 삭제
트윗 좋아요 및 북마크
리트윗 및 인용 트윗
리스트 관리

리스트 및 커뮤니티 엔드포인트

리스트 상세 및 멤버
커뮤니티 정보
타임라인 트윗

검색 엔드포인트

트윗, 사용자, 미디어 검색
고급 검색 연산자
필터 및 정렬 옵션

요금제 제한

현재 공개 요금제의 분당 요청 제한은 다음과 같습니다.

Free: 분당 10회 요청
Pro: 분당 60회 요청
Ultra: 분당 120회 요청
Mega: 분당 180회 요청

비공개, 레거시 또는 맞춤형 요금제의 제한은 다를 수 있습니다. 분당 제한으로 인한 429에는 제한된 지수 백오프와 더 낮은 동시성을 사용하세요. 요금제 요청 허용량을 모두 사용한 경우 짧은 재시도로 해결되지 않으므로 대시보드에서 현재 사용량과 구독 옵션을 확인하세요.

사용량 기반 결제(PAYG) 보조 잔액

고객은 Billing에서 일회성 PAYG 충전을 수동으로 구매할 수 있습니다. 10,000유닛은 미화 $5, 20,000유닛은 $10, 40,000유닛은 $20, 100,000유닛은 $50입니다. 충전은 자동 갱신되지 않습니다. TweetAPI는 사용 가능한 무료 요금제 또는 구독 허용량을 먼저 사용한 뒤 유효한 PAYG 잔액을 자동으로 사용합니다. 구독을 취소해도 유효한 PAYG 유닛은 계속 사용할 수 있습니다. PAYG만 사용할 때는 분당 60회로 제한되며, 더 높은 속도 제한의 활성 요금제가 있으면 그 제한이 유지됩니다.

PAYG 유닛은 결제 정산 성공 후 365일 뒤 만료됩니다. 충전이 적용되면 아직 유효한 지갑 전체에 기존 만료일과 정산일로부터 365일 후 중 더 늦은 날짜가 적용됩니다. 이미 만료된 유닛은 복구되지 않습니다. 충전 적용이 지연되어 지갑이 먼저 만료되면 기존 만료일 전에 결제했다는 사실만으로 연장이 보장되지는 않습니다. 만료 전에 결제했지만 적용이 지연됐다면 support@tweetapi.com으로 연락하여 확인된 처리 오류에 대한 검토와 정정 또는 적절한 해결을 요청하세요. Billing과 결제 확인에는 최종 만료 시각이 UTC로 표시됩니다.

유닛은 반환된 트윗 수가 아니라 API 사용량을 측정합니다. 대부분의 계량 호출은 1유닛이며, /tw-v2/xchat/send는 10유닛, /tw-v2/auth/login은 50유닛입니다. HTTP 200–499인 계량 응답은 400, 401, 403, 429를 제외하고 과금됩니다. 과금 가능한 빈 결과, 페이지네이션 요청, 별도로 제출된 각 재시도 또는 반복 요청도 유닛을 사용합니다.

환불 시 유닛은 비례해 회수되며 정수 유닛으로 올림됩니다. 결제 분쟁이 발생하면 이미 환불로 회수된 유닛을 제외하고 해당 구매의 전체 유닛이 회수됩니다. 부족분은 PAYG를 잠그지만 유효한 구독에는 영향을 주지 않습니다. 충전금은 사용 가능한 유닛을 추가하기 전에 부족분을 먼저 상환합니다. 잘못된 차감, 지급되지 않은 유닛 또는 결제 분쟁은 support@tweetapi.com으로 문의하세요. 해결을 요청하기 위해 추가 유닛을 구매할 필요는 없습니다. 이용약관 및 환불 정보 (영어로 제공되는 페이지)를 확인하세요(영어). 강행법상 권리는 제한되지 않습니다.

오류 처리

TweetAPI는 표준 HTTP 상태 코드를 사용하여 성공 또는 실패를 나타냅니다.

일반 오류 코드

400s Errors

400BAD_REQUESTBad Request - Invalid parameters

401UNAUTHORIZEDUnauthorized - Invalid API key

404NOT_FOUNDNot Found - Resource doesn't exist

429RATE_LIMITToo Many Requests

500s Errors

500INTERNAL_ERRORInternal Server Error

오류 응답 형식

모든 오류는 일관된 형식을 따릅니다.

{
  "statusCode": 400,
  "message": "Invalid username parameter"
}

권장 사항

항상 응답 상태 코드를 확인하세요.
디버깅을 위해 오류 응답을 기록하세요.
재시도에는 지수 백오프를 구현하세요.
속도 제한을 적절히 처리하세요.

보안 권장 사항

API 키를 공개하거나 버전 관리에 커밋하지 마세요.
보안 강화를 위해 키를 정기적으로 교체하세요.
애플리케이션에서 API 키를 저장할 때는 환경 변수를 사용하세요.
비정상 활동을 감지할 수 있도록 대시보드에서 사용량을 모니터링하세요.

지원

도움이 필요하거나 질문이 있다면 다음 채널로 문의하세요.

support@tweetapi.com으로 이메일 보내기
Telegram에서 @tweetapi 지원팀에 문의하기

AI용 문서