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를 제공하고, 비동기 작업이 끝나기를 기다린 뒤, 해당 작업에 저장된 정규화된 레코드를 읽습니다.
- 찾으려는 공개 동영상을 설명하는 구체적인 텍스트 검색어를 정합니다.
- query를 /v1/douyin/video-search로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패를 보고할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 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 onlyDouyin 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으로 대체하지 마세요.
관련 API
Douyin Video Search API 외에 Douyin의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Douyin Live Room Detail API — 숫자형 방 ID로 알고 있는 Douyin 라이브 방송 하나를 가져오며, 정규화된 방송 맥락, 호스트 정보, 미디어, 공개된 시청자 수를 포함합니다.
- Douyin User Profile API
- Douyin User Videos API
- Douyin Video Comments API
- Douyin Video Detail API