TweetAPI 문서

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

첫 API 요청 보내기

일회성 무료 체험 요청 100회로 시작하세요. 분당 최대 10회 요청할 수 있으며, 신용카드나 유료 플랜은 필요하지 않습니다. 체험 크레딧은 만료되지 않습니다.

TweetAPI 계정 (영어로 제공되는 페이지)을 만드세요. 무료 API 이용 권한이 자동으로 준비됩니다.
API Keys (영어로 제공되는 페이지)에서 Create Key를 선택하고 이름을 입력한 뒤 전체 키를 저장하세요. 전체 키는 생성할 때만 표시됩니다. 저장하지 않았다면 새 키를 만드세요.
아래의 미리 설정된 요청을 열고 키를 선택한 다음 Try It!을 눌러 공개 프로필을 조회하세요. 이 요청에는 별도의 X 계정 인증이 필요하지 않습니다.
응답에서 200 상태 코드와 data가 포함된 JSON 객체를 확인하세요. Playground는 실제 API를 호출하며 요청 이용량을 차감합니다.
자체 애플리케이션에서 사용하려면 아래 환경 변수를 설정하고 예제 중 하나를 실행하세요.

미리 설정된 Playground 열기 (Playground는 영어로 제공됩니다.)

로컬에서 같은 요청 실행하기

YOUR_API_KEY를 저장한 전체 키로 바꾸세요. 코드를 실행할 터미널에서 환경 변수를 설정하세요. 키는 서버에 보관하고 프런트엔드 코드에 넣거나 Git에 커밋하지 마세요.

macOS / Linux:

export TWEETAPI_API_KEY='YOUR_API_KEY'

PowerShell:

$env:TWEETAPI_API_KEY = 'YOUR_API_KEY'

cURL (Bash)

curl --fail-with-body \
  'https://api.tweetapi.com/tw-v2/user/by-username?username=elonmusk' \
  -H "X-API-Key: ${TWEETAPI_API_KEY:?Set TWEETAPI_API_KEY first}"

Python SDK

pip install tweetapi로 SDK를 설치하세요. 아래 코드를 quickstart.py로 저장하고 python quickstart.py를 실행하세요.

import os
from tweetapi import TweetAPI

client = TweetAPI(api_key=os.environ["TWEETAPI_API_KEY"])
user = client.user.get_by_username(username="elonmusk")
print(user["data"])

Node.js SDK (Node.js 18 이상)

npm install tweetapi-node로 SDK를 설치하세요. 아래 코드를 quickstart.mjs로 저장하고 node quickstart.mjs를 실행하세요.

import TweetAPI from "tweetapi-node";

const apiKey = process.env.TWEETAPI_API_KEY;
if (!apiKey) throw new Error("Set TWEETAPI_API_KEY first");
const client = new TweetAPI({ apiKey });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data);

첫 요청이 실패한 경우

환경 변수가 설정되지 않았거나 401이 반환된 경우: TWEETAPI_API_KEY에 키 목록의 가려진 값이 아닌 전체 키를 설정하세요.
계정 설정이 끝나지 않은 경우: 설정 화면에서 Check again을 선택하세요. 계속 이용할 수 없다면 지원팀에 문의하세요.
429: 오류 메시지를 확인하세요. 분당 제한이라면 요청 속도를 낮추고 횟수를 제한한 백오프로 재시도하세요. 이용량을 소진했다면 Billing (영어로 제공되는 페이지)을 확인하세요.
503: 서비스를 일시적으로 이용할 수 없습니다. Retry-After 헤더가 있다면 따르고, 재시도 횟수를 제한하세요.

기본 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 명세 (영어로 제공되는 페이지)
문서화된 82개 작업을 모두 포함하는 전체 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은 500유닛입니다. 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용 문서