douyin/
video-search

텍스트 검색어로 공개 Douyin 동영상의 고정된 첫 페이지를 검색하여 정규화된 캡션, 작성자 정보, 미디어, 길이, 타임스탬프, 확인 가능한 공개 참여도를 제공합니다.

Douyin Video Search API

텍스트 검색어
고정된 첫 페이지
정규화된 동영상
요청당 0.1 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Douyin Video Search

Douyin Video Search는 비어 있지 않은 텍스트 검색어를 범위가 정해진 공개 동영상 데이터셋으로 만듭니다. 작업마다 오프셋 0의 1페이지에 대한 공급자 요청을 고정으로 한 번 보내고, 반환된 레코드를 SocQ의 reel-video 형태로 저장해 이후 일관되게 읽을 수 있게 합니다.

Douyin Video Search API 주요 기능

  • 필드 하나로 끝나는 검색 사양query만 제출합니다. 이 엔드포인트는 results_limit 같은 선언되지 않은 입력을 거부하며, 공급자 토큰이나 내부 식별자도 필요하지 않습니다.
  • 범위가 정해진 원본 요청모든 작업은 호출자에게 공급자 페이지네이션 제어를 노출하지 않고, 오프셋 0의 1페이지를 공급자에게 요청합니다.
  • 정규화된 reel-video 레코드일관된 결과 스키마로 확인 가능한 텍스트, 작성자, 미디어, 길이, 타임스탬프, 공개된 재생·좋아요·댓글·공유 수를 읽습니다.
  • 비동기 저장 결과 조회한 번 제출하고 작업을 폴링하며, 완료된 작업이 응답 한 페이지보다 많은 레코드를 저장했을 때만 SocQ의 결과 커서를 사용합니다.

Douyin Video Search API 매개변수

매개변수필수설명
query필수비어 있지 않아야 하는 텍스트 검색어로, 필수 값입니다. 공급자의 키워드 필드에 매핑되며, 페이지와 오프셋은 백엔드가 고정합니다.

Douyin Video Search API 사용 방법

비어 있지 않은 query를 제공하고, 비동기 작업이 끝나기를 기다린 뒤, 해당 작업에 저장된 정규화된 레코드를 읽습니다.

  1. 찾으려는 공개 동영상을 설명하는 구체적인 텍스트 검색어를 정합니다.
  2. query를 /v1/douyin/video-search로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패를 보고할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽습니다. has_more가 true이면 작업 결과 요청에 next_cursor를 전달해 저장된 SocQ 레코드를 이어서 확인합니다.
curl -X POST "https://api.socq.ai/v1/douyin/video-search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"street food"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items; next_cursor pages stored SocQ results only

Douyin Video Search API 추천 활용 사례

  • 주제 중심 동영상 탐색: 상품, 주제, 이벤트, 조사 문구 하나에 대해 반환된 공개 동영상을 범위가 정해진 스냅샷으로 만듭니다.
  • 크리에이터 맥락 검토: 반환된 캡션과 미디어를 확인 가능한 공개 작성자 필드와 연결해 정성 조사와 데이터셋 정보 보강에 활용합니다.
  • 포맷·미디어 분석: 확인 가능한 동영상 미디어, 썸네일, 크기, 길이를 원본 레코드 및 검색어 맥락과 함께 검토합니다.
  • 공개된 참여도 스냅샷: collected_at을 관측 시각으로 보존한 채, 확인 가능한 재생, 좋아요, 댓글, 공유 수를 비교합니다.

Douyin Video Search API 활용 팁

  • 작업을 제출하기 전에 자체 인터페이스에서 공백이 아닌 의미 있는 검색어 입력을 필수로 검사하세요.
  • results_limit, page, offset, search_id, 공급자 커서는 SocQ 공개 요청 스키마에 없으므로 보내지 마세요.
  • 반환된 결과는 전체 검색 색인이나 호출자가 조절하는 순위 구간이 아니라 공급자 응답 한 번 분량으로 취급하세요.
  • GET /v1/tasks/{task_id}의 cursor와 limit은 저장된 결과를 읽을 때만 사용하세요. limit의 기본값은 50이며 1~500 범위를 받습니다.
  • collected_at을 보관하고, 선택 항목인 작성자, 미디어, 게시 시각, 길이, 개별 지표 필드를 처리할 때 누락된 값을 0으로 대체하지 마세요.

Douyin Video Search API 외에 Douyin의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

다른 플랫폼 둘러보기

Douyin 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Douyin Video Search API — 자주 묻는 질문

Douyin Video Search API는 텍스트 검색어 하나로 공개 Douyin 동영상의 고정된 첫 페이지를 검색해 정규화된 reel-video 레코드를 반환합니다.

query만 받으며, 비어 있지 않은 문자열이어야 합니다. 이 엔드포인트는 results_limit, page, offset, 호출자가 지정하는 공급자 커서를 받지 않습니다.

아니요. 백엔드는 공급자 요청 한 번에 항상 1페이지와 오프셋 0을 보내며, 원본 페이지네이션 제어를 제공하지 않습니다.

GET /v1/tasks/{task_id}가 반환하는 next_cursor는 완료된 작업에 대해 SocQ에 이미 저장된 레코드를 이어서 읽는 값입니다. 다른 Douyin 원본 페이지를 가져오지 않습니다.

결과는 reel-video 스키마를 따르며 ID, URL, 텍스트, 공개 작성자 정보, 미디어, 길이, 게시·수집 시각, 해시태그, 멘션, 오디오, 공개된 재생·좋아요·댓글·공유 수를 포함할 수 있습니다. 선택 필드는 null이거나 비어 있을 수 있습니다.

작업이 성공할 때마다 단일 공급자 요청이 반환한 레코드 수와 관계없이 고정 0.10 SocQ 크레딧이 차감됩니다.