Douyin Video Detail
Douyin 동영상 상세 레코드는 알고 있는 공개 동영상 URL을 정규화된 콘텐츠, 크리에이터, 미디어, 시간, 공개된 참여도 필드와 연결합니다. 정확한 동영상 링크를 이미 가지고 있고, 정보 보강·검토·이후 비교를 위해 일관된 레코드가 하나 필요한 워크플로에 유용합니다.
Douyin Video Detail API 주요 기능
- 지원되는 Douyin URLdouyin.com, iesdouyin.com 또는 지원되는 서브도메인의 URL 하나를 받습니다. /video/가 있으면 그 뒤에는 숫자형 ID가 와야 합니다.
- 범위가 정해진 단일 동영상 결과공급자 상세 요청을 한 번 실행해, 원본 페이지네이션이나 results_limit 없이 정규화된 동영상 레코드를 최대 1건 저장합니다.
- 캡션과 크리에이터 정보확인 가능한 동영상 텍스트와 함께 정규화된 크리에이터 ID, 사용자 이름, 표시 이름, 프로필 URL, 아바타, 계정 플래그를 반환합니다.
- 미디어와 길이 필드확인 가능한 동영상·이미지 참조, 미리보기, 크기, 미디어 길이, 정규화된 duration_seconds 필드를 유지합니다.
- 시각이 기록된 참여도 스냅샷확인 가능한 좋아요, 댓글, 공유, 재생, 조회 수를 실시간 카운터로 보여 주지 않고 published_at, collected_at과 함께 제공합니다.
Douyin Video Detail API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
url | 필수 | douyin.com, iesdouyin.com 또는 지원되는 서브도메인의 URL로, 비어 있지 않아야 하는 필수 값입니다. /video/가 있으면 그 뒤에 숫자형 ID가 와야 하며, 작업당 URL은 하나만 받습니다. |
Douyin Video Detail API 사용 방법
지원되는 Douyin 동영상 URL 하나를 제출하고, 비동기 작업을 추적한 뒤, 성공하면 저장된 정규화된 결과를 읽습니다.
- DOUYIN_VIDEO_URL을 호스트가 douyin.com, iesdouyin.com 또는 서브도메인인 공개 URL로 설정합니다. /video/ 구간이 있으면 그 뒤에 숫자형 ID가 와야 합니다.
- url 문자열을 /v1/douyin/video-detail로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다. 작업이 끝나기 전에는 결과 필드를 사용할 수 없습니다.
- 성공하면 data.results.items를 읽습니다. 공급자는 항목을 최대 1개 만들며, limit과 next_cursor는 SocQ의 저장된 결과 조회에 속합니다.
curl -X POST "https://api.socq.ai/v1/douyin/video-detail" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$DOUYIN_VIDEO_URL\"}"
# Poll GET /v1/tasks/{task_id}
# Read the normalized video from data.results.itemsDouyin Video Detail API 추천 활용 사례
- 알고 있는 동영상 카탈로그 정보 보강: 승인된 Douyin 동영상 링크에 정규화된 식별 정보, 캡션, 크리에이터, 게시 시각, 길이, 미디어, 출처 필드를 추가합니다.
- 탐색 결과와 상세 조회 연결: Douyin 사용자 동영상 또는 동영상 검색 레코드에서 보관해 둔 지원 동영상 URL을 집중 상세 조회의 정확한 입력으로 사용합니다.
- 특정 시점 비교 준비: 성공한 결과를 collected_at과 함께 반복 저장해, 정해진 일정에 따른 공개 참여도 스냅샷을 비교합니다.
Douyin Video Detail API 활용 팁
- 공급자가 제대로 확인하려면 지원되는 호스트 이름의 공개 동영상 URL을 직접 사용하세요. /video/가 포함되어 있다면 숫자형 동영상 ID를 그대로 유지해야 합니다.
- 이 엔드포인트에는 신뢰할 수 있는 범용 기본값이 없으므로, 실제 공개 동영상 URL이 생길 때까지 플레이그라운드 입력란은 비워 두세요.
- 공개 요청은 url만 받으므로 작업마다 URL을 하나씩 제출하고, results_limit, cursor, 관련 없는 ID는 보내지 마세요.
- 누락된 크리에이터, 미디어, 오디오, 해시태그, 멘션, 참여도 필드는 빈 문자열이나 0이 아니라 확인할 수 없는 값으로 취급하세요.
- 지표 비교에는 collected_at을, 콘텐츠 시간순 정렬에는 published_at을 사용하세요. 두 값은 서로 다른 시점을 나타냅니다.
- 동영상 댓글까지 이어서 수집하려면, 상세 조회 작업이 댓글로 확장된다고 가정하지 말고 지원되는 동영상 URL을 별도의 댓글 엔드포인트에 전달하세요.
관련 API
Douyin Video Detail API 외에 Douyin의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Douyin Live Room Detail API — 숫자형 방 ID로 알고 있는 Douyin 라이브 방송 하나를 가져오며, 정규화된 방송 맥락, 호스트 정보, 미디어, 공개된 시청자 수를 포함합니다.
- Douyin User Profile API
- Douyin User Videos API
- Douyin Video Comments API
- Douyin Video Search API