XHS（小红书）사용 가이드

TikHub OpenAPI（https://api.tikhub.io）를 기반으로 정리한 샤오홍슈 인터페이스 문서입니다.

공통 설명

a. 호출 전략: 여러 시리즈를 조합하여 사용（중요）

샤오홍슈 인터페이스에서 현재 가장 안정적인 것은 App V2 시리즈입니다. 모든 사용자는 "메인 시리즈 + 1~2개 예비 시리즈" 조합 전략을 강력히 권장하며, 2~3개 시리즈를 함께 사용해 전체 업무 가용성을 높이세요.

b. 호출 우선순위: App V2（추천）> App V1（대체）> Web V3（세 번째 예비）

App V2는 주력 추천 시리즈로, 현재 가장 안정적이고 데이터가 가장 완전하므로 우선 선택을 권장합니다. App V1은 App V2와 필드 기준이 유사하여 첫 번째 예비 대체로 적합합니다. Web V3는 기업 사용자를 대상으로 개방된 세 번째 예비 Web 채널로, xsec_token이 필요하며（공유 링크에서 추출 가능）, 반환 데이터 차원은 App V2 / App V1보다 적습니다. 따라서 기업 사용자라도 여러 시리즈를 적절히 조합해 사용해야 하며, Web V3만 단독으로 쓰는 것은 권장하지 않습니다. Web V2 / Web 시리즈는 일부 인터페이스만 사용 가능하고 안정성도 보장되지 않을 수 있어 주력으로는 비추천이며, 앞의 세 시리즈가 모두 요구를 충족하지 못할 때 보완적으로만 사용하세요.

c. 한 줄 권장사항: 한 시리즈에만 의존하지 마세요. 운영 환경에서는 최소 2개 시리즈를 주/예비로 구성하는 것을 권장합니다. 기업 사용자가 Web V3를 사용할 경우, 데이터 차원을 보완하기 위해 App V2 / App V1을 추가로 조합하세요.

d. 반환 필드 안내: App 시리즈 인터페이스（App V2 / App V1）는 구조가 유사하며, 필드 명칭도 기본적으로 서로 대응됩니다. 그러나 Web 시리즈 인터페이스（Web V3 / Web V2 / Web）는 반환 JSON 구조가 서로 다르며, 필드명, 중첩 계층, 데이터 차원도 다를 수 있습니다. 사용 시 각 인터페이스의 실제 반환 JSON 필드를 먼저 확인한 뒤 파싱 및 매핑하세요.

1. 단일 노트

샤오홍슈의 노트는 두 종류로 나뉩니다: 그림문자 노트（이미지 노트） 와 동영상 노트. App V2 시리즈는 두 유형에 대해 별도 엔드포인트를 제공하며 데이터가 가장 완전합니다. Web V3는 하나의 인터페이스로 두 유형을 모두 처리하며, 응답 필드로 구분합니다.

공통 권장사항: App V2 시리즈를 우선 사용하세요. 기업 사용자는 xsec_token를 얻을 수 있는 경우 Web V3와 함께 사용할 수 있습니다.

종합 예시: 세 시리즈를 조합하여 단일 노트 상세 가져오기

아래는 메인 시리즈（App V2）→ 예비 1（App V1）→ 예비 2（Web V3） 조합 호출 방식을 보여주는 예시 코드입니다. 우선순위에 따라 순차적으로 시도하며, 앞의 것이 성공하면 바로 반환하고 실패하면 다음으로 폴백합니다.

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

NOTE_ID = "697c0eee000000000a03c308"
XSEC_TOKEN = "ABxxxxxxxxxxxxxx"   # Required for Web V3, extract from share link / Web V3 需要，可从分享链接抽取
IS_VIDEO = False                  # Note type: True=video note, False=image note / 笔记类型：True=视频笔记，False=图文笔记


# --- Primary: App V2 / 主系列：App V2 ---
def fetch_by_app_v2(note_id: str, is_video: bool):
    if is_video:
        path = "/api/v1/xiaohongshu/app_v2/get_video_note_detail"
    else:
        path = "/api/v1/xiaohongshu/app_v2/get_image_note_detail"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"note_id": note_id})


# --- Fallback 1: App V1 (image notes only; no video download URL, not recommended for videos) / 备用 1：App V1（仅图文有效，视频不含下载链接，不建议用于视频）---
def fetch_by_app_v1(note_id: str):
    path = "/api/v1/xiaohongshu/app/get_note_info"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"note_id": note_id})


# --- Fallback 2: Web V3 (enterprise users only, requires xsec_token) / 备用 2：Web V3（企业用户专用，需要 xsec_token）---
def fetch_by_web_v3(note_id: str, xsec_token: str):
    path = "/api/v1/xiaohongshu/web_v3/fetch_note_detail"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"note_id": note_id, "xsec_token": xsec_token})


# --- Try all three series in order / 三系列依次尝试 ---
def get_note_detail(note_id: str, xsec_token: str, is_video: bool):
    # 1) Primary: App V2 / 主系列：App V2
    try:
        r = fetch_by_app_v2(note_id, is_video)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    # 2) Fallback 1: App V1 (skip this step for video notes) / 备用 1：App V1（视频笔记建议跳过此步）
    if not is_video:
        try:
            r = fetch_by_app_v1(note_id)
            if r.ok and r.json().get("code") == 200:
                return {"source": "app_v1", "data": r.json()}
        except Exception as e:
            print("App V1 调用失败：", e)

    # 3) Fallback 2: Web V3 / 备用 2：Web V3
    try:
        r = fetch_by_web_v3(note_id, xsec_token)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = get_note_detail(NOTE_ID, XSEC_TOKEN, IS_VIDEO)
print(result)

안내: 위의 성공 판단（code == 200）은 예시 작성입니다. 실제로는 각 시리즈의 반환 JSON 필드에 따라 판단하세요. 시리즈마다 반환 구조가 다르므로, 각 시리즈별로 별도의 파싱 로직을 작성하는 것을 권장합니다.

1.1 이미지 노트（그림문자 노트）

1.1.1 [App V2] 그림문자 노트 상세 가져오기 ⭐ 추천

그림문자 노트의 전체 상세 데이터（이미지 주소, 제목, 본문, 태그, 상호작용 데이터 등）를 가져옵니다.

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_image_note_detail
공식 문서：docs.tikhub.io/420136391e0
파라미터：
- note_id (string, 선택): 노트 ID, 예: "697c0eee000000000a03c308"
- share_text (string, 선택): 샤오홍슈 공유 링크（APP / Web 지원）
- 둘 중 하나만 사용, note_id 우선 사용；둘 다 전달하면 note_id 기준

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_image_note_detail"
params = {
    "note_id": "697c0eee000000000a03c308",
    # "share_text": "https://www.xiaohongshu.com/discovery/item/...",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

1.1.2 [App V1] 노트 정보 V1 가져오기（그림문자만, 동영상 다운로드 링크 없음）

App V1의 노트 인터페이스는 그림문자 노트에만 적용됩니다. 반환값에 동영상 다운로드 링크가 포함되지 않으므로 동영상 노트에는 사용하지 마세요. 동영상 노트는 App V2의 get_video_note_detail를 사용하세요.

방법：GET
경로：/api/v1/xiaohongshu/app/get_note_info
공식 문서：docs.tikhub.io/310965839e0
파라미터：
- note_id (string, 선택)
- share_text (string, 선택)
- 둘 중 하나만 사용, note_id 우선

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_note_info"
params = {
    "note_id": "697c0eee000000000a03c308",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

1.1.3 [Web V3] 노트 상세 가져오기（그림문자/동영상 공용）

Web V3 엔드포인트로, 그림문자/동영상 공용입니다. xsec_token이 필요합니다（공유 링크에서 추출, 위의 "연계 도구 인터페이스" 참고）。

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_note_detail
공식 문서：docs.tikhub.io/438852168e0
파라미터：
- note_id (string, 필수)
- xsec_token (string, 필수)

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_note_detail"
params = {
    "note_id": "697c0eee000000000a03c308",
    "xsec_token": "ABxxxxxxxxxxxxxx",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

1.2 동영상 노트

동영상 노트에는 App V1의 get_note_info를 사용하지 마세요. 이 인터페이스의 반환 내용에는 동영상 다운로드 링크가 포함되지 않습니다. 아래의 App V2 또는 Web V3를 사용하세요.

1.2.1 [App V2] 동영상 노트 상세 가져오기 ⭐ 추천

동영상 노트의 전체 상세 데이터（동영상 주소, 커버, 길이, 제목, 본문, 상호작용 데이터 등）를 가져옵니다.

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_video_note_detail
공식 문서：docs.tikhub.io/420136392e0
파라미터：
- note_id (string, 선택): 예: "697c0eee000000000a03c308"
- share_text (string, 선택)
- 둘 중 하나만 사용, note_id 우선

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_video_note_detail"
params = {
    "note_id": "697c0eee000000000a03c308",
    # "share_text": "https://www.xiaohongshu.com/discovery/item/...",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

1.2.2 [Web V3] 노트 상세 가져오기（동영상 공용）

그림문자와 동일한 엔드포인트이며, note_id + xsec_token로 호출하면 됩니다.

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_note_detail
공식 문서：docs.tikhub.io/438852168e0

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_note_detail"
params = {
    "note_id": "697c0eee000000000a03c308",
    "xsec_token": "ABxxxxxxxxxxxxxx",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

2. 사용자 정보

user_id를 통해 샤오홍슈 사용자의 공개 프로필（닉네임, 아바타, 소개, 팔로워 수, 팔로잉 수, 노트 수 등）을 가져옵니다. 세 시리즈 모두 사용자 정보 인터페이스를 제공합니다. App V2의 필드가 가장 완전하며, App V1 / Web V3는 예비용으로 적합합니다.

공통 권장사항: App V2 시리즈를 우선 사용하세요. user_id만 있는 경우에도 App V1 / Web V3를 사용할 수 있습니다.

💡 user_id를 어떻게 가져오는지 모르겠나요? 먼저 /api/v1/xiaohongshu/app/get_user_id_and_xsec_token 도구 인터페이스（공식 문서）를 사용해, 임의의 샤오홍슈 사용자 홈 공유 링크（긴 링크/짧은 링크 모두 가능）를 넣으면 user_id와 xsec_token를 파싱할 수 있습니다. 그런 다음 아래의 사용자 정보 인터페이스에 넣으면 됩니다. 자세한 내용은 아래 2.3을 참고하세요.

종합 예시: 세 시리즈를 조합하여 사용자 정보 가져오기

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

USER_ID = "61b46d790000000010008153"


# --- Primary: App V2 / 主系列：App V2 ---
def fetch_user_by_app_v2(user_id: str):
    path = "/api/v1/xiaohongshu/app_v2/get_user_info"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"user_id": user_id})


# --- Fallback 1: App V1 / 备用 1：App V1 ---
def fetch_user_by_app_v1(user_id: str):
    path = "/api/v1/xiaohongshu/app/get_user_info"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"user_id": user_id})


# --- Fallback 2: Web V3 / 备用 2：Web V3 ---
def fetch_user_by_web_v3(user_id: str):
    path = "/api/v1/xiaohongshu/web_v3/fetch_user_info"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"user_id": user_id})


# --- Try all three series in order / 三系列依次尝试 ---
def get_user_info(user_id: str):
    # 1) Primary: App V2 / 主系列：App V2
    try:
        r = fetch_user_by_app_v2(user_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    # 2) Fallback 1: App V1 / 备用 1：App V1
    try:
        r = fetch_user_by_app_v1(user_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v1", "data": r.json()}
    except Exception as e:
        print("App V1 调用失败：", e)

    # 3) Fallback 2: Web V3 / 备用 2：Web V3
    try:
        r = fetch_user_by_web_v3(user_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = get_user_info(USER_ID)
print(result)

안내: 위의 성공 판단（code == 200）은 예시 작성입니다. 실제로는 각 시리즈의 반환 JSON 필드에 따라 판단하세요. 시리즈마다 반환 구조가 다르므로, 각 시리즈별로 별도의 파싱 로직을 작성하는 것을 권장합니다.

2.1 [App V2] 사용자 정보 가져오기 ⭐ 추천

지정한 사용자의 상세 정보를 가져옵니다. 닉네임, 아바타, 소개, 팔로워 수, 팔로잉 수, 노트 수 등을 포함합니다.

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_user_info
공식 문서：docs.tikhub.io/420136395e0
파라미터：
- user_id (string, 선택): 사용자 ID, 예: "61b46d790000000010008153"
- share_text (string, 선택): 샤오홍슈 사용자 공유 링크（APP / Web 지원）
- 둘 중 하나만 사용, user_id 우선 사용；둘 다 전달하면 user_id 기준

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_user_info"
params = {
    "user_id": "61b46d790000000010008153",
    # "share_text": "https://www.xiaohongshu.com/user/profile/...",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

2.2 [App V1] 사용자 정보 가져오기

App V1의 사용자 정보 인터페이스입니다.

방법：GET
경로：/api/v1/xiaohongshu/app/get_user_info
공식 문서：docs.tikhub.io/310965845e0
파라미터：
- user_id (string, 필수)

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_user_info"
params = {
    "user_id": "61b46d790000000010008153",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

2.3 [App V1] 연계 도구：사용자 공유 링크에서 user_id와 xsec_token 추출

손에 사용자 홈 공유 링크만 있는 경우（긴 링크/짧은 링크 모두 지원）, 이 인터페이스를 먼저 사용해 user_id와 xsec_token를 파싱한 뒤, 위의 사용자 정보 인터페이스를 호출할 수 있습니다.

방법：GET
경로：/api/v1/xiaohongshu/app/get_user_id_and_xsec_token
공식 문서：docs.tikhub.io/364605901e0
파라미터：
- share_link (string, 필수): 샤오홍슈 사용자 공유 링크

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_user_id_and_xsec_token"
params = {
    "share_link": "https://xhslink.com/m/xxxxx",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())
# Example response fields / 返回示例字段:
# {
#   "data": {
#       "user_id": "61b46d790000000010008153",
#       "xsec_token": "ABxxxxxxxxxxxxxx"
#   }
# }

2.4 [Web V3] 사용자 정보 가져오기

Web V3의 사용자 공개 프로필 인터페이스로, user_id만 필요합니다.

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_user_info
공식 문서：docs.tikhub.io/438852177e0
파라미터：
- user_id (string, 필수)

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_user_info"
params = {
    "user_id": "61b46d790000000010008153",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

3. 사용자 작품

user_id에 따라 해당 사용자가 게시한 노트 목록（그림문자/동영상 혼합）을 가져옵니다. 모든 인터페이스는 커서 페이지네이션（cursor）을 사용합니다. App V2 시리즈는 추가로 "사용자 공개 저장 노트 목록" 인터페이스（faved notes）를 제공하며, App V1 / Web V3는 "게시된 노트"만 지원합니다.

공통 권장사항: App V2 시리즈를 우선 사용하세요. user_id만 있는 경우에도 App V1 / Web V3를 사용할 수 있습니다.

💡 user_id을 어떻게 가져오는지 모르겠나요? 위의 2.3 도구 인터페이스（공식 문서）를 참고하세요.

종합 예시: 세 시리즈를 조합하여 사용자의 게시된 노트 가져오기

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

USER_ID = "61b46d790000000010008153"
CURSOR = ""   # Empty for first request; pass previous response's cursor for pagination / 首次请求留空；翻页时传上一次返回的 cursor


# --- Primary: App V2 / 主系列：App V2 ---
def fetch_user_notes_app_v2(user_id: str, cursor: str = ""):
    path = "/api/v1/xiaohongshu/app_v2/get_user_posted_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"user_id": user_id, "cursor": cursor})


# --- Fallback 1: App V1 / 备用 1：App V1 ---
def fetch_user_notes_app_v1(user_id: str, cursor: str = ""):
    path = "/api/v1/xiaohongshu/app/get_user_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"user_id": user_id, "cursor": cursor})


# --- Fallback 2: Web V3 / 备用 2：Web V3 ---
def fetch_user_notes_web_v3(user_id: str, cursor: str = "", num: int = 30):
    path = "/api/v1/xiaohongshu/web_v3/fetch_user_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS,
                        params={"user_id": user_id, "cursor": cursor, "num": num})


# --- Try all three series in order / 三系列依次尝试 ---
def get_user_notes(user_id: str, cursor: str = ""):
    # 1) Primary: App V2 / 主系列：App V2
    try:
        r = fetch_user_notes_app_v2(user_id, cursor)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    # 2) Fallback 1: App V1 / 备用 1：App V1
    try:
        r = fetch_user_notes_app_v1(user_id, cursor)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v1", "data": r.json()}
    except Exception as e:
        print("App V1 调用失败：", e)

    # 3) Fallback 2: Web V3 / 备用 2：Web V3
    try:
        r = fetch_user_notes_web_v3(user_id, cursor)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = get_user_notes(USER_ID, CURSOR)
print(result)

안내: 위의 성공 판단（code == 200）은 예시 작성입니다. 실제로는 각 시리즈의 반환 JSON 필드에 따라 판단하세요. 시리즈마다 반환 구조가 다르므로, 각 시리즈별로 별도의 파싱 로직을 작성하는 것을 권장합니다.

3.1 [App V2] 사용자가 게시한 노트 목록 가져오기 ⭐ 추천

지정한 사용자가 게시한 노트 목록을 가져오며, 커서 페이지네이션을 사용합니다.

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_user_posted_notes
공식 문서：docs.tikhub.io/420136396e0
파라미터：
- user_id (string, 선택): 사용자 ID, 예: "61b46d790000000010008153"
- share_text (string, 선택): 샤오홍슈 사용자 공유 링크（APP / Web 지원）
- 둘 중 하나만 사용, user_id 우선；둘 다 전달하면 user_id 기준
- cursor (string, 선택): 페이지 커서, 첫 요청은 비워둠；다음 페이지에서는 이전 응답의 notes 목록 마지막 노트의 cursor를 사용（경로 예시：$.data.data.notes[-1].cursor）

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_user_posted_notes"
params = {
    "user_id": "61b46d790000000010008153",
    "cursor": "",   # Empty for first request / 首次留空
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

3.2 [App V2] 사용자가 공개 저장한 노트 목록 가져오기（App V2 전용）

지정한 사용자가 공개 저장한 노트 목록을 가져옵니다（사용자가 직접 게시한 것이 아니라, 그가 저장한 콘텐츠입니다）. 커서 페이지네이션을 사용합니다. 이 인터페이스는 App V2에서만 제공되며, App V1 / Web V3에는 대응 기능이 없습니다.

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_user_faved_notes
공식 문서：docs.tikhub.io/420136397e0
파라미터：
- user_id (string, 선택): 예: "5a8cf39111be10466d285d6b"
- share_text (string, 선택)
- 둘 중 하나만 사용, user_id 우선
- cursor (string, 선택): 페이지 커서, 첫 요청은 비워둠；다음 페이지에서는 이전 페이지의 마지막 노트의 note_id

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_user_faved_notes"
params = {
    "user_id": "5a8cf39111be10466d285d6b",
    "cursor": "",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

3.3 [App V1] 사용자 작품 목록 가져오기

App V1의 사용자 작품 인터페이스로, 게시된 노트만 지원하며 커서 페이지네이션을 사용합니다.

방법：GET
경로：/api/v1/xiaohongshu/app/get_user_notes
공식 문서：docs.tikhub.io/310965846e0
파라미터：
- user_id (string, 필수)
- cursor (string, 선택): 첫 요청은 비워둠；다음 페이지에서는 이전 페이지 notes 목록의 마지막 노트의 note_id를 사용

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_user_notes"
params = {
    "user_id": "61b46d790000000010008153",
    "cursor": "",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

반환 구조（핵심 필드）：

notes[]：노트 배열, 각 항목에는 note_id, type（normal=그림문자 / video=동영상）, display_title, desc, liked_count, cover, user 등이 포함
cursor：다음 페이지 커서
has_more：추가 데이터 존재 여부

3.4 [Web V3] 사용자 노트 목록 가져오기

Web V3의 사용자 작품 인터페이스로, 커서 페이지네이션을 사용하며 단일 페이지 수를 지정할 수 있습니다（최대 30）.

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_user_notes
공식 문서：docs.tikhub.io/438852178e0
파라미터：
- user_id (string, 필수)
- cursor (string, 선택): 페이지 커서
- num (integer, 선택): 페이지당 수량, 기본 30, 최대 30

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_user_notes"
params = {
    "user_id": "61b46d790000000010008153",
    "cursor": "",
    "num": 30,
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

4. 댓글

샤오홍슈의 댓글은 두 단계로 나뉩니다: 1차 댓글（노트 아래의 댓글 목록） 과 2차 댓글（특정 댓글 아래의 답글/하위 댓글 목록）. 세 시리즈 모두 이 두 단계 인터페이스를 제공합니다. App V2의 필드가 가장 풍부하며, App V1 / Web V3는 예비용으로 적합합니다.

공통 권장사항: App V2 시리즈를 우선 사용하세요. Web V3 인터페이스는 xsec_token이 필요합니다（공유 링크에서 추출 가능, 1. 단일 노트 종합 예시 / 2.3 도구 인터페이스 참고）。

4.1 1차 댓글（노트 아래의 댓글 목록）

종합 예시: 세 시리즈를 조합하여 1차 댓글 가져오기

아래는 메인 시리즈（App V2）→ 예비 1（App V1）→ 예비 2（Web V3） 조합 호출 방식을 보여주는 예시 코드입니다.

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

NOTE_ID = "697c0eee000000000a03c308"
XSEC_TOKEN = "ABxxxxxxxxxxxxxx"   # Required for Web V3 / Web V3 需要


# --- Primary: App V2 / 主系列：App V2 ---
def fetch_comments_app_v2(note_id: str, cursor: str = "", index: int = 0):
    path = "/api/v1/xiaohongshu/app_v2/get_note_comments"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "note_id": note_id,
        "cursor": cursor,
        "index": index,
        "pageArea": "UNFOLDED",
        "sort_strategy": "latest_v2",
    })


# --- Fallback 1: App V1 / 备用 1：App V1 ---
def fetch_comments_app_v1(note_id: str, start: str = ""):
    path = "/api/v1/xiaohongshu/app/get_note_comments"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "note_id": note_id,
        "start": start,
        "sort_strategy": 1,
    })


# --- Fallback 2: Web V3 / 备用 2：Web V3 ---
def fetch_comments_web_v3(note_id: str, xsec_token: str, cursor: str = ""):
    path = "/api/v1/xiaohongshu/web_v3/fetch_note_comments"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "note_id": note_id,
        "xsec_token": xsec_token,
        "cursor": cursor,
    })


# --- Try all three series in order / 三系列依次尝试 ---
def get_note_comments(note_id: str, xsec_token: str):
    try:
        r = fetch_comments_app_v2(note_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    try:
        r = fetch_comments_app_v1(note_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v1", "data": r.json()}
    except Exception as e:
        print("App V1 调用失败：", e)

    try:
        r = fetch_comments_web_v3(note_id, xsec_token)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = get_note_comments(NOTE_ID, XSEC_TOKEN)
print(result)

안내: 위의 성공 판단（code == 200）은 예시 작성입니다. 실제로는 각 시리즈의 반환 JSON 필드에 따라 판단하세요.

4.1.1 [App V2] 노트 댓글 목록 가져오기 ⭐ 추천

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_note_comments
공식 문서：docs.tikhub.io/420136394e0
파라미터：
- note_id (string, 선택): 노트 ID
- share_text (string, 선택): 공유 링크（note_id와 둘 중 하나, note_id 우선）
- cursor (string, 선택): 페이지 커서, 첫 요청은 비워둠
- index (integer, 선택): 댓글 인덱스, 첫 요청은 0 전달
- pageArea (string, 선택): 접힘 상태, UNFOLDED（기본）/ FOLDED
- sort_strategy (string, 선택): 정렬, default / latest_v2（기본） / like_count

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_note_comments"
params = {
    "note_id": "697c0eee000000000a03c308",
    "cursor": "",
    "index": 0,
    "pageArea": "UNFOLDED",
    "sort_strategy": "latest_v2",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

4.1.2 [App V1] 노트 댓글 가져오기

방법：GET
경로：/api/v1/xiaohongshu/app/get_note_comments
공식 문서：docs.tikhub.io/310965840e0
파라미터：
- note_id (string, 필수)
- start (string, 선택): 페이지 이동 커서, 첫 요청은 비워둠；두 가지 형식을 지원합니다 —— 간단 형식（예: "682b0133000000001c03618d"） 또는 JSON 형식（예: {"cursor":"...","index":2,"pageArea":"UNFOLDED"}）
- sort_strategy (integer, 선택): 1-기본 정렬（기본）/ 2-최신 댓글

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_note_comments"
params = {
    "note_id": "697c0eee000000000a03c308",
    "start": "",
    "sort_strategy": 1,
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

4.1.3 [Web V3] 노트 댓글 가져오기

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_note_comments
공식 문서：docs.tikhub.io/438852169e0
파라미터：
- note_id (string, 필수)
- xsec_token (string, 필수)：공유 링크에서 추출 가능
- cursor (string, 선택): 페이지 커서

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_note_comments"
params = {
    "note_id": "697c0eee000000000a03c308",
    "xsec_token": "ABxxxxxxxxxxxxxx",
    "cursor": "",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

4.2 2차 댓글（하위 댓글 / 답글 목록）

특정 1차 댓글 아래의 모든 답글（하위 댓글）을 가져옵니다. 이 역시 세 시리즈가 모두 지원합니다. Web V3에서는 이 파라미터가 root_comment_id이고, 다른 두 시리즈는 comment_id입니다.

종합 예시: 세 시리즈를 조합하여 하위 댓글 가져오기

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

NOTE_ID = "699916e6000000001d0253da"
COMMENT_ID = "PARENT_COMMENT_ID"  # Top-level comment ID / 一级评论 ID
XSEC_TOKEN = "ABxxxxxxxxxxxxxx"   # Required for Web V3 / Web V3 需要


def fetch_sub_app_v2(note_id, comment_id, cursor="", index=1):
    path = "/api/v1/xiaohongshu/app_v2/get_note_sub_comments"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "note_id": note_id,
        "comment_id": comment_id,
        "cursor": cursor,
        "index": index,
    })


def fetch_sub_app_v1(note_id, comment_id, start=""):
    path = "/api/v1/xiaohongshu/app/get_sub_comments"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "note_id": note_id,
        "comment_id": comment_id,
        "start": start,
    })


def fetch_sub_web_v3(note_id, root_comment_id, xsec_token, cursor="", num=10):
    path = "/api/v1/xiaohongshu/web_v3/fetch_sub_comments"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "note_id": note_id,
        "root_comment_id": root_comment_id,
        "xsec_token": xsec_token,
        "cursor": cursor,
        "num": num,
    })


def get_sub_comments(note_id, comment_id, xsec_token):
    try:
        r = fetch_sub_app_v2(note_id, comment_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    try:
        r = fetch_sub_app_v1(note_id, comment_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v1", "data": r.json()}
    except Exception as e:
        print("App V1 调用失败：", e)

    try:
        r = fetch_sub_web_v3(note_id, comment_id, xsec_token)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = get_sub_comments(NOTE_ID, COMMENT_ID, XSEC_TOKEN)
print(result)

4.2.1 [App V2] 노트 2차 댓글 목록 가져오기 ⭐ 추천

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_note_sub_comments
공식 문서：docs.tikhub.io/420748830e0
파라미터：
- note_id (string, 선택)
- share_text (string, 선택)（note_id와 둘 중 하나, note_id 우선）
- comment_id (string, 필수): 부모 댓글 ID
- cursor (string, 선택): 첫 요청은 비워둠, 다음 페이지에서는 $.data.cursor에서 가져옴
- index (integer, 선택): 첫 요청은 1 전달, 다음 페이지에서는 $.data.cursor에서 가져옴

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_note_sub_comments"
params = {
    "note_id": "699916e6000000001d0253da",
    "comment_id": "PARENT_COMMENT_ID",
    "cursor": "",
    "index": 1,
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

4.2.2 [App V1] 하위 댓글 가져오기

방법：GET
경로：/api/v1/xiaohongshu/app/get_sub_comments
공식 문서：docs.tikhub.io/310965841e0
파라미터：
- note_id (string, 필수)
- comment_id (string, 필수): 1차 댓글 ID
- start (string, 선택): 페이지 이동 커서, 이전 페이지의 마지막 하위 댓글 ID에서 가져옴（예: "6806642d000000001f01991b"）

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_sub_comments"
params = {
    "note_id": "697c0eee000000000a03c308",
    "comment_id": "PARENT_COMMENT_ID",
    "start": "",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

4.2.3 [Web V3] 하위 댓글 가져오기

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_sub_comments
공식 문서：docs.tikhub.io/438852170e0
파라미터：
- note_id (string, 필수)
- root_comment_id (string, 필수): 부모 댓글 ID
- xsec_token (string, 필수)
- num (integer, 선택): 반환 수량, 기본 10
- cursor (string, 선택): 페이지 커서

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_sub_comments"
params = {
    "note_id": "697c0eee000000000a03c308",
    "root_comment_id": "PARENT_COMMENT_ID",
    "xsec_token": "ABxxxxxxxxxxxxxx",
    "num": 10,
    "cursor": "",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

5. 검색

샤오홍슈 검색은 두 종류로 나뉩니다: 노트 검색 과 사용자 검색.

노트 검색：App V2 / App V1 / Web V3 세 시리즈 모두 제공하며, App V2의 필드가 가장 풍부합니다（정렬, 노트 유형, 시간 필터, AI 모드 등 지원）。
사용자 검색：App V2와 Web V3만 제공하며, App V1에는 사용자 검색 인터페이스가 없습니다.

공통 권장사항: App V2 시리즈를 우선 사용하세요. 페이지 이동 시 첫 검색 응답에서 반환된 search_id / session_id을 함께 전달하세요（시리즈마다 파라미터명이 약간 다릅니다）。

5.1 노트 검색

종합 예시: 세 시리즈를 조합하여 노트 검색

아래는 메인 시리즈（App V2）→ 예비 1（App V1）→ 예비 2（Web V3） 조합 호출 방식을 보여주는 예시 코드입니다.

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

KEYWORD = "美食推荐"
PAGE = 1


# --- Primary: App V2 / 主系列：App V2 ---
def search_notes_app_v2(keyword: str, page: int = 1):
    path = "/api/v1/xiaohongshu/app_v2/search_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "keyword": keyword,
        "page": page,
        "sort_type": "general",
        "note_type": "不限",
        "time_filter": "不限",
    })


# --- Fallback 1: App V1 / 备用 1：App V1 ---
def search_notes_app_v1(keyword: str, page: int = 1):
    path = "/api/v1/xiaohongshu/app/search_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "keyword": keyword,
        "page": page,
        "sort_type": "general",
        "filter_note_type": "不限",
        "filter_note_time": "不限",
    })


# --- Fallback 2: Web V3 / 备用 2：Web V3 ---
def search_notes_web_v3(keyword: str, page: int = 1):
    path = "/api/v1/xiaohongshu/web_v3/fetch_search_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "keyword": keyword,
        "page": page,
        "sort": "general",
        "note_type": 0,
    })


def search_notes(keyword: str, page: int = 1):
    try:
        r = search_notes_app_v2(keyword, page)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    try:
        r = search_notes_app_v1(keyword, page)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v1", "data": r.json()}
    except Exception as e:
        print("App V1 调用失败：", e)

    try:
        r = search_notes_web_v3(keyword, page)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = search_notes(KEYWORD, PAGE)
print(result)

안내: 위의 성공 판단（code == 200）은 예시 작성입니다. 실제로는 각 시리즈의 반환 JSON 필드에 따라 판단하세요. 페이지 이동 시 첫 응답의 search_id / session_id를 그대로 전달하는 것을 잊지 마세요.

5.1.1 [App V2] 노트 검색 ⭐ 추천

방법：GET
경로：/api/v1/xiaohongshu/app_v2/search_notes
공식 문서：docs.tikhub.io/420136398e0
파라미터：
- keyword (string, 필수): 검색 키워드, 예: "美食推荐"
- page (integer, 선택): 페이지 번호, 1부터 시작
- sort_type (string, 선택): 정렬, general（종합, 기본）/ time_descending（최신）/ popularity_descending（좋아요 많음）/ comment_descending（댓글 많음）/ collect_descending（저장 많음）/ english_preferred（영어 우선）
- note_type (string, 선택): 노트 유형, 不限（기본）/ 视频笔记 / 普通笔记 / 直播笔记
- time_filter (string, 선택): 게시 시간, 不限（기본）/ 一天内 / 一周内 / 半年内
- search_id (string, 선택): 페이지 이동 시 첫 응답의 값을 전달
- search_session_id (string, 선택): 페이지 이동 시 첫 응답의 값을 전달
- source (string, 선택): 출처, 기본 explore_feed
- ai_mode (integer, 선택): AI 모드, 0（끄기, 기본）/ 1（켜기）

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/search_notes"
params = {
    "keyword": "美食推荐",
    "page": 1,
    "sort_type": "general",
    "note_type": "不限",
    "time_filter": "不限",
    # Pass search_id and search_session_id from first response for pagination / 翻页时需要带上首次响应里的 search_id 和 search_session_id
    # "search_id": "...",
    # "search_session_id": "...",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

5.1.2 [App V1] 노트 검색

방법：GET
경로：/api/v1/xiaohongshu/app/search_notes
공식 문서：docs.tikhub.io/310965843e0
파라미터：
- keyword (string, 필수)
- page (integer, 필수): 페이지 번호, 1부터 시작
- search_id (string, 선택): 페이지 이동 시 첫 응답의 값을 전달
- session_id (string, 선택): 페이지 이동 시 첫 응답의 값을 전달
- sort_type (string, 선택): general（기본）/ time_descending / popularity_descending / comment_descending / collect_descending
- filter_note_type (string, 선택): 不限（기본）/ 视频笔记 / 普通笔记
- filter_note_time (string, 선택): 不限（기본）/ 一天内 / 一周内 / 半年内

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app/search_notes"
params = {
    "keyword": "美食推荐",
    "page": 1,
    "sort_type": "general",
    "filter_note_type": "不限",
    "filter_note_time": "不限",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

5.1.3 [Web V3] 노트 검색

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_search_notes
공식 문서：docs.tikhub.io/438852171e0
파라미터：
- keyword (string, 필수)
- page (integer, 선택): 기본 1
- sort (string, 선택): general（종합, 기본）/ time_descending（최신）/ popularity_descending（인기）
- note_type (integer, 선택): 0=전체（기본）/ 1=그림문자 / 2=동영상

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_search_notes"
params = {
    "keyword": "美食推荐",
    "page": 1,
    "sort": "general",
    "note_type": 0,
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

5.2 사용자 검색

⚠️ 주의：App V1에는 사용자 검색 인터페이스가 없습니다. 이 섹션은 App V2와 Web V3 두 시리즈만 있습니다.

종합 예시: 두 시리즈를 조합하여 사용자 검색

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

KEYWORD = "美食博主"
PAGE = 1


# --- Primary: App V2 / 主系列：App V2 ---
def search_users_app_v2(keyword: str, page: int = 1, search_id: str = ""):
    path = "/api/v1/xiaohongshu/app_v2/search_users"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "keyword": keyword,
        "page": page,
        "search_id": search_id,
    })


# --- Fallback: Web V3 / 备用：Web V3 ---
def search_users_web_v3(keyword: str, page: int = 1):
    path = "/api/v1/xiaohongshu/web_v3/fetch_search_users"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "keyword": keyword,
        "page": page,
    })


def search_users(keyword: str, page: int = 1):
    try:
        r = search_users_app_v2(keyword, page)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    try:
        r = search_users_web_v3(keyword, page)
        if r.ok and r.json().get("code") == 200:
            return {"source": "web_v3", "data": r.json()}
    except Exception as e:
        print("Web V3 调用失败：", e)

    return None


result = search_users(KEYWORD, PAGE)
print(result)

5.2.1 [App V2] 사용자 검색 ⭐ 추천

페이지당 20개 결과를 고정 반환하며, 페이지 이동을 지원합니다.

방법：GET
경로：/api/v1/xiaohongshu/app_v2/search_users
공식 문서：docs.tikhub.io/420136399e0
파라미터：
- keyword (string, 필수): 검색 키워드, 예: "美食博主"
- page (integer, 선택): 페이지 번호, 1부터 시작
- search_id (string, 선택): 페이지 이동 시 첫 응답의 값을 전달
- source (string, 선택): 출처, 기본 explore_feed

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/search_users"
params = {
    "keyword": "美食博主",
    "page": 1,
    # Pass search_id from first response for pagination / 翻页时带上首次响应里的 search_id
    # "search_id": "...",
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

5.2.2 [Web V3] 사용자 검색

방법：GET
경로：/api/v1/xiaohongshu/web_v3/fetch_search_users
공식 문서：docs.tikhub.io/438852172e0
파라미터：
- keyword (string, 필수)
- page (integer, 선택): 기본 1

python
url = f"{BASE_URL}/api/v1/xiaohongshu/web_v3/fetch_search_users"
params = {
    "keyword": "口红",
    "page": 1,
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())

6. 주제

샤오홍슈 주제 관련 인터페이스는 두 부분으로 나뉩니다: 주제 상세 와 주제 아래의 노트 목록.

⚠️ 중요 안내：

Web V3 시리즈에는 주제 인터페이스가 없습니다. 이 섹션은 App V2와 App V1 두 시리즈만 있습니다.

App V1의 기존 인터페이스 /api/v1/xiaohongshu/app/get_notes_by_topic는 폐기됨. 이 섹션의 get_topic_notes을 사용하세요.

모든 인터페이스는 page_id（주제/주제 태그 ID）를 유일 식별자로 사용합니다.

6.1 주제 상세

App V2만 주제 상세 인터페이스를 제공합니다（주제명, 조회수, 토론 수, 공유 정보 등）. App V1 / Web V3에는 대응 기능이 없습니다.

6.1.1 [App V2] 주제 상세 가져오기 ⭐ App V2 전용

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_topic_info
공식 문서：docs.tikhub.io/420136407e0
파라미터：
- page_id (string, 필수): 주제 페이지 ID, 예: "5c1cc866febed9000184b7c1"
- source (string, 선택): 출처, 기본 normal
- note_id (string, 선택): 출처 노트 ID, 노트에서 주제로 이동할 때 전달 가능

python
import requests

BASE_URL = "https://api.tikhub.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_topic_info"
params = {
    "page_id": "5c1cc866febed9000184b7c1",
    "source": "normal",
    # "note_id": "...",  # Optional: pass when navigating from a note / 从笔记跳转过来时可带
}
r = requests.get(url, headers=HEADERS, params=params)
print(r.json())
# Response contains page_info (name/views/discussions), tabs, share_info, etc. / 返回包含 page_info（名称/浏览量/讨论数）、tabs、share_info 等

6.2 주제 노트 목록（주제 아래의 노트）

특정 주제/주제 태그 아래의 노트 목록을 가져옵니다. App V2와 App V1 모두 제공하지만, 파라미터와 페이지 이동 필드 차이가 커서 각각 맞춰야 합니다.

종합 예시: 두 시리즈를 조합하여 주제 노트 가져오기

python
import requests
import time

BASE_URL = "https://api.tikhub.io"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "accept": "application/json",
}

PAGE_ID = "5c1cc866febed9000184b7c1"


# --- Primary: App V2 / 主系列：App V2 ---
def topic_feed_app_v2(page_id: str, sort: str = "trend"):
    path = "/api/v1/xiaohongshu/app_v2/get_topic_feed"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "page_id": page_id,
        "sort": sort,        # trend (hottest) / time (latest) | trend(最热) / time(最新)
    })


# --- Fallback: App V1 / 备用：App V1 ---
def topic_notes_app_v1(page_id: str, sort: str = "hot"):
    path = "/api/v1/xiaohongshu/app/get_topic_notes"
    return requests.get(f"{BASE_URL}{path}", headers=HEADERS, params={
        "page_id": page_id,
        "first_load_time": str(int(time.time() * 1000)),  # Millisecond timestamp / 毫秒级时间戳
        "sort": sort,        # hot (general) / time (latest) / trend (hottest) | hot(综合) / time(最新) / trend(最热)
    })


def get_topic_notes(page_id: str):
    try:
        r = topic_feed_app_v2(page_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v2", "data": r.json()}
    except Exception as e:
        print("App V2 调用失败：", e)

    try:
        r = topic_notes_app_v1(page_id)
        if r.ok and r.json().get("code") == 200:
            return {"source": "app_v1", "data": r.json()}
    except Exception as e:
        print("App V1 调用失败：", e)

    return None


result = get_topic_notes(PAGE_ID)
print(result)

안내: 위의 성공 판단（code == 200）은 예시 작성입니다. 실제로는 각 시리즈의 반환 JSON 필드에 따라 판단하세요. 페이지 이동 시 해당 커서 필드를 그대로 전달하는 것을 잊지 마세요（두 시리즈의 필드가 다르며, 아래 참고）。

6.2.1 [App V2] 주제 노트 목록 가져오기 ⭐ 추천

방법：GET
경로：/api/v1/xiaohongshu/app_v2/get_topic_feed
공식 문서：docs.tikhub.io/420136408e0
파라미터：
- page_id (string, 필수): 주제 페이지 ID
- sort (string, 선택): trend（인기, 기본）/ time（최신）
- cursor_score (string, 선택): 페이지 이동 커서 점수, 다음 페이지에서는 이전 페이지 마지막 item의 cursor_score 전달
- last_note_id (string, 선택): 페이지 이동 시 이전 페이지 마지막 노트 ID（items[-1].id）
- last_note_ct (string, 선택): 페이지 이동 시 이전 페이지 마지막 노트 생성 시간（items[-1].create_time）
- session_id (string, 선택): 세션 ID, 페이지 이동 시 동일하게 유지
- first_load_time (string, 선택): 최초 로드 타임스탬프, 페이지 이동 시 동일하게 유지
- source (string, 선택): 출처, 기본 normal

python
url = f"{BASE_URL}/api/v1/xiaohongshu/app_v2/get_topic_feed"

# First request: pass only page_id and sort / 首次请求：只传 page_id 和 sort
params = {
    "page_id": "5c1cc866febed9000184b7c1",
    "sort": "trend",
}
r = requests.get(url, headers=HEADERS, params=params)
data = r.json()
print(data)

# Next page: pass through the following fields from the first response / 翻页请求：从首次响应中取下列字段透传
# items = data["data"]["items"]
# next_params = {
#     "page_id": "5c1cc866febed9000184b7c1",
#     "sort": "trend",
#     "cursor_score": items[-1]["cursor_score"],
#     "last_note_id": items[-1]["id"],
#     "last_note_ct": items[-1]["create_time"],
#     "session_id": data["data"]["session_id"],
#     "first_load_time": data["data"]["first_load_time"],
# }

6.2.2 [App V1] 주제 태그로 작품 가져오기（폐기된 `get_notes_by_topic` 대체）

⚠️ App V1의 기존 인터페이스 /api/v1/xiaohongshu/app/get_notes_by_topic는 폐기되었습니다. 이 인터페이스를 직접 사용하세요.

방법：GET
경로：/api/v1/xiaohongshu/app/get_topic_notes
공식 문서：docs.tikhub.io/454758056e0
파라미터：
- page_id (string, 필수): 주제 태그 ID
- first_load_time (string, 필수): 최초 요청 타임스탬프（밀리초）, Python에서 가져오기：int(time.time() * 1000)
- sort (string, 선택): hot（종합, 기본）/ time（최신）/ trend（인기）
- last_note_ct (string, 선택): 페이지 이동 시 이전 페이지 마지막 노트의 create_time 전달
- last_note_id (string, 선택): 페이지 이동 시 이전 페이지 마지막 노트 ID 전달
- cursor_score (string, 선택): 페이지 이동 시 이전 페이지 마지막 노트의 cursor_score 전달
- session_id (string, 선택): 세션 ID, 최초에는 서버가 생성하며 페이지 이동 시 다시 전달

python
import time

url = f"{BASE_URL}/api/v1/xiaohongshu/app/get_topic_notes"

# First request / 首次请求
params = {
    "page_id": "5c1cc866febed9000184b7c1",
    "first_load_time": str(int(time.time() * 1000)),
    "sort": "hot",
}
r = requests.get(url, headers=HEADERS, params=params)
data = r.json()
print(data)

# Next page: keep page_id / first_load_time unchanged, pass session_id and last_* through / 翻页请求：保持 page_id / first_load_time 不变，把 session_id 和 last_* 透传
# notes = data["data"]["notes"]
# next_params = {
#     "page_id": "5c1cc866febed9000184b7c1",
#     "first_load_time": params["first_load_time"],
#     "sort": "hot",
#     "session_id": data["data"]["session_id"],
#     "last_note_id": notes[-1]["id"],
#     "last_note_ct": notes[-1]["note"]["create_time"],
#     "cursor_score": notes[-1].get("cursor_score", ""),
# }

XHS（小红书）사용 가이드

목차

공통 설명

1. 단일 노트

종합 예시: 세 시리즈를 조합하여 단일 노트 상세 가져오기

1.1 이미지 노트（그림문자 노트）

1.1.1 [App V2] 그림문자 노트 상세 가져오기 ⭐ 추천

1.1.2 [App V1] 노트 정보 V1 가져오기（그림문자만, 동영상 다운로드 링크 없음）

1.1.3 [Web V3] 노트 상세 가져오기（그림문자/동영상 공용）

1.2 동영상 노트

1.2.1 [App V2] 동영상 노트 상세 가져오기 ⭐ 추천

1.2.2 [Web V3] 노트 상세 가져오기（동영상 공용）

2. 사용자 정보

종합 예시: 세 시리즈를 조합하여 사용자 정보 가져오기

2.1 [App V2] 사용자 정보 가져오기 ⭐ 추천

2.2 [App V1] 사용자 정보 가져오기

2.3 [App V1] 연계 도구：사용자 공유 링크에서 user_id와 xsec_token 추출

2.4 [Web V3] 사용자 정보 가져오기

3. 사용자 작품

종합 예시: 세 시리즈를 조합하여 사용자의 게시된 노트 가져오기

3.1 [App V2] 사용자가 게시한 노트 목록 가져오기 ⭐ 추천

3.2 [App V2] 사용자가 공개 저장한 노트 목록 가져오기（App V2 전용）

3.3 [App V1] 사용자 작품 목록 가져오기

3.4 [Web V3] 사용자 노트 목록 가져오기

4. 댓글

4.1 1차 댓글（노트 아래의 댓글 목록）

종합 예시: 세 시리즈를 조합하여 1차 댓글 가져오기

4.1.1 [App V2] 노트 댓글 목록 가져오기 ⭐ 추천

4.1.2 [App V1] 노트 댓글 가져오기

4.1.3 [Web V3] 노트 댓글 가져오기

4.2 2차 댓글（하위 댓글 / 답글 목록）

종합 예시: 세 시리즈를 조합하여 하위 댓글 가져오기

4.2.1 [App V2] 노트 2차 댓글 목록 가져오기 ⭐ 추천

4.2.2 [App V1] 하위 댓글 가져오기

4.2.3 [Web V3] 하위 댓글 가져오기

5. 검색

5.1 노트 검색

종합 예시: 세 시리즈를 조합하여 노트 검색

5.1.1 [App V2] 노트 검색 ⭐ 추천

5.1.2 [App V1] 노트 검색

5.1.3 [Web V3] 노트 검색

5.2 사용자 검색

종합 예시: 두 시리즈를 조합하여 사용자 검색

5.2.1 [App V2] 사용자 검색 ⭐ 추천

5.2.2 [Web V3] 사용자 검색

6. 주제

6.1 주제 상세

6.1.1 [App V2] 주제 상세 가져오기 ⭐ App V2 전용

6.2 주제 노트 목록（주제 아래의 노트）

종합 예시: 두 시리즈를 조합하여 주제 노트 가져오기

6.2.1 [App V2] 주제 노트 목록 가져오기 ⭐ 추천

6.2.2 [App V1] 주제 태그로 작품 가져오기（폐기된 get_notes_by_topic 대체）

6.2.2 [App V1] 주제 태그로 작품 가져오기（폐기된 `get_notes_by_topic` 대체）