{"openapi":"3.0.3","info":{"title":"SOOP 오늘의 클립왕 공개 API","version":"1.1.0","description":"지정한 스트리머의 현재 또는 가장 최근 방송 시작 이후 생성된 라이브 클립을 생성자별로 집계합니다. includeCatch=true로 라이브 캐치를 함께 집계할 수 있습니다. API 키 없이 사용할 수 있으며 브라우저의 교차 출처 GET 요청을 지원합니다. 오늘은 달력상의 자정이 아닌 현재·최근 방송 시작을 뜻합니다. SOOP 원본 응답에 불변 원본 방송 ID가 없어 live_user 유형과 생성 시각을 조합하며, 이전 방송 콘텐츠가 방송 재시작 이후로 인코딩·업로드 지연된 경우 회차를 구분할 수 없습니다."},"servers":[{"url":"/"}],"security":[],"paths":{"/api/public/v1/stations/{bjId}/clip-creators":{"get":{"operationId":"getLatestBroadcastClipCreatorRanking","summary":"오늘의 클립왕: 현재·최근 방송의 클립·캐치 생성자 순위","description":"기본값은 CLIP의 clip_type=live_user만 집계합니다. includeCatch=true이면 CATCH의 catch_type=live_user도 포함합니다. 원본 스트리머가 일치하고 목록·상세 생성 시각이 방송 시작 이상 countedAt 이하인 콘텐츠만 집계하며 과거 다시보기에서 만든 review_user는 두 유형 모두 제외합니다. 동일 titleNo는 한 번만 세고 생성자는 userId로 구분합니다. 기본값은 clipCount, 캐치 포함 시 totalCount 내림차순이며 동률이면 userId 오름차순입니다. 공동 순위는 1, 1, 3 방식입니다. 캐치 포함 시 clipCount·totalClips·pendingClipCount·unknownCreatorClipCount는 계속 클립만 의미하며 캐치 수는 별도 필드로 제공합니다. 생성자 ID 미확인 콘텐츠는 유형별 unknownCreator 수와 총수에만 포함하고 순위에서 제외합니다. SOOP가 인코딩 중(-6227)임을 명시한 후보는 유형별 pending 수에만 포함하고 complete=false로 반환합니다. 이 후보가 실제 집계 대상인지는 상세 준비 후 결정되므로 총수에 pending 수를 더해 최종 수로 해석하면 안 됩니다. 방송 이력이 없으면 broadcast=null과 0건을 반환합니다. 종료된 최근 방송은 isLive=false, broadNo=null입니다. 첫 조회는 개별 상세 확인으로 오래 걸릴 수 있습니다(기본 전체 제한 120초). 결과는 기본 15초 동안 내부 캐시되며 캐시 응답은 원래 countedAt을 유지합니다. 인코딩 중 상태 외의 불완전 집계, 집계 중 방송 변경은 성공 숫자 대신 오류를 반환합니다.","parameters":[{"name":"bjId","in":"path","required":true,"description":"SOOP 스트리머 ID. 대문자는 소문자로 정규화합니다.","schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]{1,64}$"},"example":"example_bj"},{"name":"includeCatch","in":"query","required":false,"description":"true이면 라이브 캐치를 포함해 totalCount로 순위를 매깁니다. 생략 또는 false이면 기존 클립 전용 응답을 유지합니다. true 또는 false 문자열을 한 번만 전달하세요.","schema":{"type":"boolean","default":false},"example":true}],"responses":{"200":{"description":"검증된 생성자 순위. includeCatch=true이면 합산 응답, 생략·false이면 클립 전용 응답. 인코딩 중 후보가 있으면 complete=false.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","enum":["*"]}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PublicClipCreatorRanking"},{"$ref":"#/components/schemas/PublicContentCreatorRanking"}]},"examples":{"live":{"summary":"방송 중, 공동 1위와 생성자 미확인 1건","value":{"streamerId":"example_bj","broadcast":{"broadNo":123456789,"startedAt":"2026-09-23T14:30:00.000Z","isLive":true},"scope":"latest_broadcast_live_user_clips","countedAt":"2026-09-24T01:00:00.000Z","complete":true,"pendingClipCount":0,"totalClips":9,"totalCreators":3,"unknownCreatorClipCount":1,"creators":[{"rank":1,"userId":"viewer_a","userNick":"시청자 A","clipCount":3},{"rank":1,"userId":"viewer_b","userNick":null,"clipCount":3},{"rank":3,"userId":"viewer_c","userNick":"시청자 C","clipCount":2}]}},"pendingEncoding":{"summary":"인코딩 중 후보 2건을 제외한 잠정 순위","value":{"streamerId":"example_bj","broadcast":{"broadNo":123456789,"startedAt":"2026-09-23T14:30:00.000Z","isLive":true},"scope":"latest_broadcast_live_user_clips","countedAt":"2026-09-24T01:00:00.000Z","complete":false,"pendingClipCount":2,"totalClips":9,"totalCreators":3,"unknownCreatorClipCount":1,"creators":[{"rank":1,"userId":"viewer_a","userNick":"시청자 A","clipCount":3},{"rank":1,"userId":"viewer_b","userNick":null,"clipCount":3},{"rank":3,"userId":"viewer_c","userNick":"시청자 C","clipCount":2}]}},"offline":{"summary":"종료된 최근 방송","value":{"streamerId":"example_bj","broadcast":{"broadNo":null,"startedAt":"2026-09-23T14:30:00.000Z","isLive":false},"scope":"latest_broadcast_live_user_clips","countedAt":"2026-09-24T01:00:00.000Z","complete":true,"pendingClipCount":0,"totalClips":9,"totalCreators":3,"unknownCreatorClipCount":1,"creators":[{"rank":1,"userId":"viewer_a","userNick":"시청자 A","clipCount":3},{"rank":1,"userId":"viewer_b","userNick":null,"clipCount":3},{"rank":3,"userId":"viewer_c","userNick":"시청자 C","clipCount":2}]}},"noBroadcastHistory":{"summary":"방송 이력 없음","value":{"streamerId":"example_bj","broadcast":null,"scope":"latest_broadcast_live_user_clips","countedAt":"2026-09-24T01:00:00.000Z","complete":true,"pendingClipCount":0,"totalClips":0,"totalCreators":0,"unknownCreatorClipCount":0,"creators":[]}},"includingCatches":{"summary":"includeCatch=true: 클립·캐치 합산 공동 순위와 캐치만 생성한 사용자","value":{"streamerId":"example_bj","broadcast":{"broadNo":123456789,"startedAt":"2026-09-23T14:30:00.000Z","isLive":true},"scope":"latest_broadcast_clips_and_catches","countedAt":"2026-09-24T01:00:00.000Z","complete":true,"pendingClipCount":0,"totalClips":6,"totalCreators":3,"unknownCreatorClipCount":1,"creators":[{"rank":1,"userId":"viewer_a","userNick":"시청자 A","clipCount":3,"catchCount":1,"totalCount":4},{"rank":1,"userId":"viewer_b","userNick":null,"clipCount":0,"catchCount":4,"totalCount":4},{"rank":3,"userId":"viewer_c","userNick":"시청자 C","clipCount":2,"catchCount":1,"totalCount":3}],"totalCatches":7,"totalCount":13,"pendingCatchCount":0,"unknownCreatorCatchCount":1}},"includingCatchesPending":{"summary":"클립 후보 2건·캐치 후보 1건 인코딩 중","value":{"streamerId":"example_bj","broadcast":{"broadNo":123456789,"startedAt":"2026-09-23T14:30:00.000Z","isLive":true},"scope":"latest_broadcast_clips_and_catches","countedAt":"2026-09-24T01:00:00.000Z","complete":false,"pendingClipCount":2,"totalClips":6,"totalCreators":3,"unknownCreatorClipCount":1,"creators":[{"rank":1,"userId":"viewer_a","userNick":"시청자 A","clipCount":3,"catchCount":1,"totalCount":4},{"rank":1,"userId":"viewer_b","userNick":null,"clipCount":0,"catchCount":4,"totalCount":4},{"rank":3,"userId":"viewer_c","userNick":"시청자 C","clipCount":2,"catchCount":1,"totalCount":3}],"totalCatches":7,"totalCount":13,"pendingCatchCount":1,"unknownCreatorCatchCount":1}},"includingCatchesNoBroadcastHistory":{"summary":"includeCatch=true, 방송 이력 없음","value":{"streamerId":"example_bj","broadcast":null,"scope":"latest_broadcast_clips_and_catches","countedAt":"2026-09-24T01:00:00.000Z","complete":true,"pendingClipCount":0,"totalClips":0,"totalCreators":0,"unknownCreatorClipCount":0,"creators":[],"totalCatches":0,"totalCount":0,"pendingCatchCount":0,"unknownCreatorCatchCount":0}}}}}},"400":{"description":"허용되지 않는 bjId 형식 또는 includeCatch 값·중복 전달","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","enum":["*"]}},"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"SOOP가 존재하지 않는 스트리머로 응답","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","enum":["*"]}},"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"SOOP 요청 실패, 개별 요청 시간 초과 또는 원본 응답 검증 실패","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","enum":["*"]}},"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"전체 집계 시간·페이지·동시 집계 상한 초과 또는 집계 중 방송 변경. 잠시 후 재시도하세요.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","enum":["*"]}},"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"description":"공개 웹 게이트웨이에서 백엔드 응답 대기 시간 초과. 잠시 후 재시도하세요.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","enum":["*"]}},"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"PublicClipCreatorRanking":{"type":"object","required":["streamerId","broadcast","scope","countedAt","complete","pendingClipCount","totalClips","totalCreators","unknownCreatorClipCount","creators"],"properties":{"streamerId":{"type":"string","description":"소문자로 정규화한 스트리머 ID"},"broadcast":{"type":"object","nullable":true,"description":"현재 또는 가장 최근 방송. 방송 이력이 없으면 null.","required":["broadNo","startedAt","isLive"],"properties":{"broadNo":{"type":"integer","format":"int64","nullable":true,"description":"방송 중 확인한 방송 번호. 방송 종료 후 null."},"startedAt":{"type":"string","format":"date-time","description":"집계 시작 기준인 방송 시작 시각(UTC)"},"isLive":{"type":"boolean","description":"집계 완료 전 마지막 방송 정보 확인 시 방송 중 여부"}}},"scope":{"type":"string","enum":["latest_broadcast_live_user_clips"]},"countedAt":{"type":"string","format":"date-time","description":"목록 조회 전 고정한 생성 시각 상한(UTC). 응답 완료 시각이 아니며 내부 캐시에서는 기존 값 유지."},"complete":{"type":"boolean","description":"pendingClipCount가 0이면 true. 원본 방송 회차 ID의 정확한 대조를 보장한다는 뜻은 아님."},"pendingClipCount":{"type":"integer","minimum":0,"description":"인코딩 중으로 상세 검증을 기다리는 후보. 다른 모든 클립 수에서 제외."},"totalClips":{"type":"integer","minimum":0,"description":"sum(creators[].clipCount) + unknownCreatorClipCount"},"totalCreators":{"type":"integer","minimum":0,"description":"creators.length. 생성자 ID 미확인 클립은 제외."},"unknownCreatorClipCount":{"type":"integer","minimum":0,"description":"대상 클립 중 생성자 ID가 없는 수. 순위에서는 제외."},"creators":{"type":"array","description":"클립 수 내림차순, 동률이면 userId 오름차순. userId로 생성자를 구분.","items":{"$ref":"#/components/schemas/RankedClipCreator"}}}},"PublicContentCreatorRanking":{"type":"object","required":["streamerId","broadcast","scope","countedAt","complete","pendingClipCount","totalClips","totalCreators","unknownCreatorClipCount","creators","totalCatches","totalCount","pendingCatchCount","unknownCreatorCatchCount"],"properties":{"streamerId":{"type":"string","description":"소문자로 정규화한 스트리머 ID"},"broadcast":{"type":"object","nullable":true,"description":"현재 또는 가장 최근 방송. 방송 이력이 없으면 null.","required":["broadNo","startedAt","isLive"],"properties":{"broadNo":{"type":"integer","format":"int64","nullable":true,"description":"방송 중 확인한 방송 번호. 방송 종료 후 null."},"startedAt":{"type":"string","format":"date-time","description":"집계 시작 기준인 방송 시작 시각(UTC)"},"isLive":{"type":"boolean","description":"집계 완료 전 마지막 방송 정보 확인 시 방송 중 여부"}}},"scope":{"type":"string","enum":["latest_broadcast_clips_and_catches"]},"countedAt":{"type":"string","format":"date-time","description":"목록 조회 전 고정한 생성 시각 상한(UTC). 응답 완료 시각이 아니며 내부 캐시에서는 기존 값 유지."},"complete":{"type":"boolean","description":"pendingClipCount와 pendingCatchCount가 모두 0이면 true. 원본 방송 회차 ID의 정확한 대조를 보장한다는 뜻은 아님."},"pendingClipCount":{"type":"integer","minimum":0,"description":"인코딩 중으로 상세 검증을 기다리는 후보. 다른 모든 클립 수에서 제외."},"totalClips":{"type":"integer","minimum":0,"description":"sum(creators[].clipCount) + unknownCreatorClipCount"},"totalCreators":{"type":"integer","minimum":0,"description":"creators.length. 클립 또는 캐치를 생성한 고유 사용자 수."},"unknownCreatorClipCount":{"type":"integer","minimum":0,"description":"대상 클립 중 생성자 ID가 없는 수. 순위에서는 제외."},"creators":{"type":"array","description":"totalCount 내림차순, 동률이면 userId 오름차순. 클립·캐치를 생성한 동일 userId는 한 행으로 합산.","items":{"$ref":"#/components/schemas/RankedContentCreator"}},"totalCatches":{"type":"integer","minimum":0,"description":"sum(creators[].catchCount) + unknownCreatorCatchCount"},"totalCount":{"type":"integer","minimum":0,"description":"totalClips + totalCatches"},"pendingCatchCount":{"type":"integer","minimum":0,"description":"인코딩 중으로 상세 검증을 기다리는 캐치 후보. 다른 모든 집계 수에서 제외."},"unknownCreatorCatchCount":{"type":"integer","minimum":0,"description":"대상 캐치 중 생성자 ID가 없는 수. 순위에서는 제외."}}},"RankedClipCreator":{"type":"object","required":["rank","userId","userNick","clipCount"],"properties":{"rank":{"type":"integer","minimum":1,"description":"공동 순위는 1, 1, 3 방식. 나보다 클립 수가 많은 생성자 수 + 1."},"userId":{"type":"string","minLength":1},"userNick":{"type":"string","nullable":true,"description":"포함된 클립 중 최근에 확인한 닉네임. 확인할 수 없으면 null."},"clipCount":{"type":"integer","minimum":1}}},"RankedContentCreator":{"type":"object","required":["rank","userId","userNick","clipCount","catchCount","totalCount"],"properties":{"rank":{"type":"integer","minimum":1,"description":"클립·캐치 합계 기준 공동 순위. 나보다 totalCount가 많은 생성자 수 + 1."},"userId":{"type":"string","minLength":1},"userNick":{"type":"string","nullable":true,"description":"포함된 클립·캐치 중 최근에 확인한 닉네임. 확인할 수 없으면 null."},"clipCount":{"type":"integer","minimum":0},"catchCount":{"type":"integer","minimum":0},"totalCount":{"type":"integer","minimum":1,"description":"clipCount + catchCount. 캐치만 생성한 사용자도 순위에 포함."}}},"ApiError":{"type":"object","required":["statusCode","message","error"],"properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"error":{"type":"string"}}}}}}