본문으로 건너뛰기

현재 방송 조회

DJ 가 지금 하고 있는 방송의 정보를 조회해요. 제목 · 시작/종료 시각 · 청취자 수 · 인사말 · 카테고리 · 채팅 얼림 상태가 한 번에 와요.

메서드 · 경로GET /v1/live
필요한 권한live.read
성공 응답200
방송 중이 아닐 때404 (OAPI_MNGR_0301)
export SPOON_BASE_URL="https://kr-openapi.spooncast.net"
export SPOON_ACCESS_TOKEN="{발급받은 access token}"

일본 지역이면 https://jp-openapi.spooncast.net 이에요 — 지역별 주소.

요청​

GET /v1/live

헤더​

이름필수설명
Authorization✔Bearer {access_token} 형식이에요.

경로 파라미터 · 쿼리 파라미터 · 요청 바디가 없어요. 어느 DJ 의 방송인지는 토큰이 정해요 — 토큰 하나가 동의한 DJ 한 명이라, 봇이 남의 방송을 지목할 자리가 없어요.

요청 예시​

curl -H "Authorization: Bearer $SPOON_ACCESS_TOKEN" "$SPOON_BASE_URL/v1/live"

응답​

{
  "liveId": 10001,
  "title": "오늘의 심야 라디오",
  "startedAt": "2026-09-01T13:00:00Z",
  "closeAirTime": "2026-09-01T15:00:00Z",
  "listenerCount": 42,
  "totalListenerCount": 137,
  "welcomeMessage": "어서 오세요! 사연은 채팅으로 남겨 주세요",
  "isChatFrozen": false,
  "categories": ["talk"],
  "tags": ["심야라디오", "사연"]
}
필드타입null설명
liveIdnumber아니오이 방송 회차를 가리키는 id 예요.
titlestring아니오방송 제목이에요.
startedAtstring아니오시작 시각이에요. ISO-8601 UTC(Z) 예요.
closeAirTimestring아니오종료 예정 시각이에요. ISO-8601 UTC(Z) 예요.
listenerCountnumber아니오지금 접속 중인 청취자 수예요.
totalListenerCountnumber아니오방송 시작부터 지금까지 다녀간 누적 인원이에요.
welcomeMessagestring아니오DJ 가 방에 걸어둔 인사말이에요. 안 적었으면 빈 문자열이에요.
isChatFrozenboolean아니오채팅이 얼어 있는지 알려줘요.
categoriesstring[]아니오방송 카테고리예요 (sing · talk …).
tagsstring[]아니오DJ 가 붙인 해시태그예요.

코드​

// live.ts — node --experimental-strip-types live.ts

interface Live {
  liveId: number;
  title: string;
  startedAt: string;
  closeAirTime: string;
  listenerCount: number;
  totalListenerCount: number;
  welcomeMessage: string;
  isChatFrozen: boolean;
  categories: string[];
  tags: string[];
}

const res = await fetch(`${process.env.SPOON_BASE_URL}/v1/live`, {
  headers: { Authorization: `Bearer ${process.env.SPOON_ACCESS_TOKEN}` },
});

if (res.status === 404) {
  console.log('방송 중이 아니에요. 잠시 뒤 다시 확인해요.');
} else if (!res.ok) {
  throw new Error(`조회 실패: ${res.status}`);
} else {
  const live = (await res.json()) as Live;
  console.log(`[${live.liveId}] ${live.title} — 청취자 ${live.listenerCount}명 (누적 ${live.totalListenerCount}명)`);
  if (live.isChatFrozen) console.log('채팅이 얼어 있어요. 지금은 발화하지 않아요.');
}
node --experimental-strip-types live.ts

주의​

isChatFrozen 이 true 면 채팅을 보낼 수 없어요. 채팅 보내기 가 실패해요. 봇도 일반 청취자와 같은 규칙을 따르기 때문이에요. 발화하기 전에 이 값을 보고 멈추면 실패를 미리 피할 수 있어요.

liveId 는 봇이 방송 회차를 구분하는 값이에요. "이번 방송에 1회만" 같은 규칙의 멱등 키로 쓰고, 재연결했을 때 같은 방송인지 새 방송인지 판단할 때도 써요. startedAt 을 대신 쓰면 값이 조금만 흔들려도 한 방송이 둘로 갈려요.

listenerCount 와 totalListenerCount 를 헷갈리지 마세요. 앞은 지금 접속 중, 뒤는 다녀간 누적이에요. 누적은 줄어들지 않아요.

방송이 켜졌는지 확인하려고 이 엔드포인트를 폴링할 필요는 없어요. 이벤트 스트림이 방송 중이 아니면 연결 전에 404 를 주니, 스트림 연결을 재시도하는 것만으로 충분해요 — 연결 루프를 보세요.

에러​

HTTPdetailCode무슨 일인가요어떻게 하나요
401없음토큰이 없거나 무효해요.DJ 에게 재연동을 안내해요.
403없음live.read 권한이 없어요.권한을 추가해 재동의를 받아요.
404OAPI_MNGR_0301방송 중이 아니에요.오류가 아니라 상태예요. 잠시 뒤 다시 불러요.
502OAPI_MNGR_2302방송 서버 오류예요.백오프 후 재시도해요.

이 표에 없는 상태도 올 수 있어요. 잘못된 메서드·Content-Type(400 · 405 · 415, OAPI_MNGR_0103) · 호출 한도(429, 본문 없음) · 서버 오류(500, OAPI_MNGR_1002)는 모든 엔드포인트에 공통이에요 — 에러 코드에 있어요.

관련 문서​