Developer API · v1

클립왕 공개 API

한 스트리머의 현재 또는 가장 최근 방송에서 만들어진 라이브 클립과 캐치를 생성자별로 조회하세요. API 키 없이 사용할 수 있으며, 외부 웹사이트에서도 호출할 수 있습니다.

요청

GET /api/public/v1/stations/{bjId}/clip-creators

bjId는 SOOP 스트리머 아이디입니다. 영문, 숫자, 밑줄, 하이픈 1~64자를 허용하며 대소문자를 구분하지 않습니다. 인증 헤더는 필요하지 않습니다. includeCatch=true를 붙이면 캐치까지 합산합니다. 생략하거나 false이면 기존 클립 전용 응답을 유지합니다. 다른 값이나 중복 쿼리는 400 오류입니다.

curl --max-time 150 \
  'https://vod.soopup.live/api/public/v1/stations/cotton1217/clip-creators?includeCatch=true'

백엔드 직접 호출도 가능합니다: https://api.soopup.live/api/public/v1/stations/{bjId}/clip-creators

첫 조회는 최대 약 2분이 걸릴 수 있습니다. 서버는 성공한 집계를 기본 15초 동안 재사용합니다. 자동 갱신은 15초 이상의 간격을 두고, 503 오류가 나면 잠시 기다린 뒤 재시도하세요.

백엔드를 직접 호출할 때 게이트웨이 시간 제한으로 504 응답을 받아도 집계는 계속될 수 있습니다. 같은 요청을 다시 보내면 진행 중인 집계나 완료된 결과를 받을 수 있습니다. 이 사이트의 공개 경로는 전체 130초 대기 범위 안에서 504 응답에 한해 한 번 자동 재시도합니다.

집계 기준

화면의 “오늘”은 달력 날짜가 아닌 현재 또는 가장 최근 방송 시작 이후를 뜻합니다. 자정을 넘긴 방송도 이어서 집계하며, 방송이 종료되면 가장 최근 방송을 보여줍니다. 화면은 라이브 클립과 캐치를 합산하며, 다시보기에서 만든 클립·캐치는 제외합니다.

SOOP 원본 데이터에 영상별 확정 방송 회차가 없어, 라이브 생성 여부와 생성 시각을 기준으로 분류합니다. 이전 방송의 영상이 다음 방송 시작 뒤 늦게 생성된 경우까지 완전히 구분할 수는 없습니다.

응답

아래는 includeCatch=true 응답과 동률 순위를 설명하기 위한 예시 데이터입니다.

{
  "streamerId": "example_bj",
  "broadcast": {
    "broadNo": 123456789,
    "startedAt": "2026-09-24T06:00:00.000Z",
    "isLive": true
  },
  "scope": "latest_broadcast_clips_and_catches",
  "countedAt": "2026-09-24T07:00:00.000Z",
  "complete": true,
  "pendingClipCount": 0,
  "pendingCatchCount": 0,
  "totalClips": 4,
  "totalCatches": 7,
  "totalCount": 11,
  "totalCreators": 3,
  "unknownCreatorClipCount": 0,
  "unknownCreatorCatchCount": 0,
  "creators": [
    {
      "rank": 1,
      "userId": "viewer_a",
      "userNick": "클립 팬 A",
      "clipCount": 3,
      "catchCount": 2,
      "totalCount": 5
    },
    {
      "rank": 1,
      "userId": "viewer_b",
      "userNick": "캐치 팬 B",
      "clipCount": 0,
      "catchCount": 5,
      "totalCount": 5
    },
    {
      "rank": 3,
      "userId": "viewer_c",
      "userNick": null,
      "clipCount": 1,
      "catchCount": 0,
      "totalCount": 1
    }
  ]
}
broadcast
방송 번호·시작 시각·현재 방송 여부. 방송 이력이 없으면 null, 종료 방송의 번호는 null일 수 있습니다.
scope
기본 요청은 latest_broadcast_live_user_clips, includeCatch=true는 latest_broadcast_clips_and_catches입니다.
countedAt
집계 기준 시각(ISO 8601 UTC). 방송 시작부터 이 시각까지 생성된 라이브 클립·캐치를 집계합니다.
creators
생성자 ID·닉네임·순위와 clipCount(클립 수). 캐치를 포함하면 catchCount(캐치 수), totalCount(합계)가 추가됩니다. 합계 내림차순이며 동률은 공동 순위(1, 1, 3)입니다. 기본 요청의 순위는 클립 수 기준입니다.
totalClips / totalCatches / totalCount
검증된 전체 클립 수 / 캐치 수 / 합계. totalClips는 항상 클립만 뜻합니다. 캐치 수와 합계 필드는 includeCatch=true일 때만 제공됩니다.
totalCreators
ID를 확인한 생성자 수. 캐치만 만든 생성자도 합산 순위에 포함됩니다.
unknownCreatorClipCount / unknownCreatorCatchCount
생성자 ID가 없어 순위에서 제외한 클립·캐치 수. 각각 totalClips와 totalCatches에는 포함됩니다. 캐치 필드는 includeCatch=true일 때만 제공됩니다.
complete / pendingClipCount / pendingCatchCount
인코딩 중 검증을 기다리는 영상이 있으면 complete는 false입니다. 대기 영상은 합계와 순위에서 제외됩니다. pendingClipCount는 클립, pendingCatchCount는 캐치 대기 수이며 캐치 필드는 includeCatch=true일 때만 제공됩니다.

오류 처리

오류는 { statusCode, message, error } 형식의 JSON으로 반환합니다. 오류를 클립 0개로 해석하지 마세요.

400
아이디 형식과 includeCatch 쿼리 값을 확인하세요.
404
해당 SOOP 스트리머를 찾을 수 없습니다.
502
SOOP 조회 또는 응답 검증에 실패했습니다. 잠시 후 재시도하세요.
503
집계 시간·조회량 제한, 동시 요청 제한 또는 방송 변경이 발생했습니다. 잠시 후 재시도하세요.
504
공개 게이트웨이의 응답 대기 시간이 초과되었습니다. 잠시 후 재시도하세요.