개발자 안내 · WordLive API

외부 서비스(LMS·설문·사내 도구 등)에서 WordLive 워드클라우드를 그대로 가져다 쓰기 위한 REST API입니다. 한국어 정규화(조사 제거·불용어·동의어), 실시간 발표 화면, 결과 저장을 그대로 씁니다.

1. 인증

내 계정 → API 키에서 키를 발급받아 모든 요청에 Authorization: Bearer wl_live_… 헤더로 보냅니다. 키는 서버 측 코드에서만 쓰세요. 브라우저에 넣으면 누구나 볼 수 있습니다. 브라우저 페이지에서는 인증이 필요 없는 공개 데이터 API(/api/public/…)나 임베드 화면(/embed/{code})을 쓰면 됩니다.

2. 엔드포인트

메서드	경로	인증	설명
POST	/api/v1/sessions	키	세션 생성 (start:true 면 즉시 시작)
GET	/api/v1/sessions	키	내가 만든 세션 목록
GET	/api/v1/sessions/{code}	선택	상태 + 워드클라우드 (소유자는 항상, 그 외는 진행 중·공개 세션만)
PATCH	/api/v1/sessions/{code}	키	시작 전 세션 수정 · public 토글
POST	/api/v1/sessions/{code}/start	키	시작 (종료 후 재시작 시 집계 이어감)
POST	/api/v1/sessions/{code}/words	키	단어 제출 (text 1건 또는 texts 최대 100건)
POST	/api/v1/sessions/{code}/close	키	종료 + 최종 결과 저장
GET	/api/public/sessions/{code}	없음	읽기 전용 공개 데이터 (브라우저에서 직접 fetch 가능)

모든 v1 응답은 CORS(*)를 허용하고 X-RateLimit-* 헤더를 포함합니다. 오류는 { "error": "CODE", "message": "설명" } 형식입니다.

3. 빠른 시작 (curl)

세션을 만들고 바로 시작한 뒤, 단어를 넣고, 결과를 읽습니다.

# 1) 세션 생성 + 시작
curl -X POST https://word.duonedu.net/api/v1/sessions \
  -H "Authorization: Bearer $WORDLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"올해 배우고 싶은 것은?","start":true,"durationMinutes":30,"maxPerUser":3}'
# → 201 { "code":"ABC234", "status":"open",
#          "urls": { "join":"https://word.duonedu.net/ABC234", "present":"…/present/ABC234",
#                    "embed":"…/embed/ABC234", "result":"…/r/ABC234", "data":"…/api/public/sessions/ABC234" } }

# 2) 단어 제출 (여러 건, 참여자별 상한을 지키려면 participantId 지정)
curl -X POST https://word.duonedu.net/api/v1/sessions/ABC234/words \
  -H "Authorization: Bearer $WORDLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts":["AI가 궁금해요","영어 회화"],"participantId":"user-42"}'
# → { "accepted":[{"text":"AI가 궁금해요","words":["ai","궁금해요"]}, …], "rejected":[], "summary":{…} }

# 3) 현재 워드클라우드
curl https://word.duonedu.net/api/v1/sessions/ABC234?limit=50 -H "Authorization: Bearer $WORDLIVE_KEY"
# → { "status":"open", "live":true, "cloud":[{"text":"ai","value":3}, …], "entryCount":12, … }

# 4) 종료
curl -X POST https://word.duonedu.net/api/v1/sessions/ABC234/close -H "Authorization: Bearer $WORDLIVE_KEY"

4. 세션 생성 옵션

question (필수, 200자 이하)
start — true 면 생성과 동시에 시작. 생략하면 초안(draft)으로 저장되고 /start 호출 때 시작
durationMinutes — 진행 시간(분, 최대 10080=1주). 0/생략이면 12시간 뒤 자동 종료
maxPerUser — 참여자 1인당 제출 상한(1~10, 기본 3). participantId를 줄 때 적용
stopwords — 추가 불용어 배열 · synonyms — {"에이아이":"AI"} 형태의 동의어 맵
fx — minimal · stage · cinema · minimal-ticker · cinema-fast · palette — indigo · chalk · dancheong · lantern · seaglass
public — 종료 후 결과 공개 여부(기본 true). false 면 소유자만 조회

5. 화면을 그대로 가져다 쓰기

실시간 화면까지 직접 만들 필요는 없습니다. 응답의 urls.embed를 iframe 으로 넣으면 발표 화면과 같은 워드클라우드가 실시간으로 갱신됩니다. 참여자는 urls.join(QR·링크)으로 들어오고, 서버에서 모은 답변은 /words로 넣으면 같은 화면에 즉시 반영됩니다.

<iframe src="https://word.duonedu.net/embed/ABC234" width="960" height="560"
        style="border:0;border-radius:16px" title="실시간 워드클라우드"></iframe>

자체 시각화를 원하면 공개 데이터 API를 브라우저에서 몇 초마다 폴링하세요 (키 불필요, CORS 허용).

const r = await fetch("https://word.duonedu.net/api/public/sessions/ABC234");
const { question, cloud } = await r.json(); // cloud: [{ text, value }, …]

6. 오류 코드

401 UNAUTHENTICATED — API 키가 없거나 폐기됨
403 FORBIDDEN — 다른 사람의 세션
404 NOT_FOUND — 없는 코드, 또는 비공개·시작 전 세션을 소유자가 아닌 사람이 조회
409 NOT_OPEN / ALREADY_STARTED — 진행 중이 아닌 세션에 제출 / 시작 후 수정 시도
422 QUESTION_* / TEXT_REQUIRED — 입력값 검증 실패
429 RATE_LIMITED — 키 1개당 분당 600회 초과 (Retry-After 헤더 참고)

7. 한도와 주의

키 1개당 분당 600회. 한 요청에 최대 100건까지 묶어 제출하면 호출 수를 아낄 수 있습니다.
제출 원문은 200자에서 잘리고, 정규화 결과가 비면 EMPTY로 거절됩니다.
세션은 소유자의 계정에 저장되며, 계정 페이지의 목록에서도 그대로 보입니다.
문의: duonedu@duonedu.net