본문으로 건너뛰기
RandNext
Esc

RandNext API

48개 RandNext 도구를 위한 무료 읽기 전용 JSON 엔드포인트입니다. API 키 없이 숫자, 색상, 날짜, 주사위 결과, 엄선 항목 등을 생성할 수 있습니다. 버전 1의 기본 경로는 /api/v1입니다.

빠른 시작

curl https://randnext.com/api/v1/jokes/random
curl "https://randnext.com/api/v1/tools/random-number?min=1&max=100&count=5&unique=true"
const res = await fetch("https://randnext.com/api/v1/quotes/random?category=wisdom");
const quote = await res.json();
console.log(`“${quote.text}” — ${quote.author}`);

엔드포인트

엄선 콘텐츠에는 목록, 랜덤, ID 조회 엔드포인트가 제공됩니다. 생성기 도구는 도구 slug 기반의 통일된 엔드포인트를 사용합니다.

요청반환값
GET /api/v1/{type}/random랜덤 항목 1개
GET /api/v1/{type}?limit=1..20{ data: Item[], count } — 중복 없는 랜덤 항목(기본 10개)
GET /api/v1/{type}/{id}ID로 항목 1개 조회(캐시 가능)
GET /api/v1/tools/{slug}지원되는 유틸리티 도구 44개 중 하나에서 결과 생성
GET /api/v1/draws/{id}추첨 선택기 추첨 기록: 커밋, 참가자 목록 해시, 추첨 시간 이후 공개되는 시드와 당첨자를 포함합니다. 기한이 된 추첨을 읽으면 결과가 공개됩니다.
GET /api/v1/draws/{id}/entries잠긴 참가자 목록을 text/plain으로 바이트 단위까지 그대로 반환합니다. SHA-256은 entries_hash입니다. 숨김 목록에는 주최자의 관리 토큰이 필요합니다.
POST /api/v1/draws/{id}/cancel주최자 전용: 추첨 시간 전에 추첨을 취소합니다. 기록은 취소 상태로 계속 공개됩니다.
PATCH /api/v1/draws/{id}주최자 전용: listed를 true 또는 false로 설정하거나 purge_entries를 true로 설정해 추첨 후 저장된 목록을 삭제합니다.
GET /api/v1/health서비스 상태
GET /api/v1/openapi.jsonOpenAPI 3.1 설명

추첨 주최자 작업은 Authorization: Bearer <관리 토큰>을 전송하며 randnext.com 또는 서버 측 코드에서만 허용됩니다. 다른 웹사이트에서는 사용할 수 없습니다. 추첨을 다시 계산하려면 randnext-draw-v1 명세를 사용하세요.

쿼리 매개변수

  • category — 농담: general, programming, dad, pun, animal, 명언: inspirational, life, work, humor, wisdom, 질문: icebreaker, classroom, friends, deep, would-you-rather, 단어: noun, verb, adjective, adverb.
  • safety — family(가족용만) 또는 general(기본값: 가족용 및 일반용). 성인 콘텐츠는 반환하지 않습니다.
  • 단어 전용: min_length, max_length (1~30), starts_with(글자 1개).
  • 생성기 매개변수는 도구마다 다릅니다. 공통 옵션은 count, min, max, group, unique, sort. 각 도구 페이지에 실행 가능한 요청 예제가 있습니다.
  • 알 수 없는 매개변수나 도구 허용 범위를 벗어난 값은 400 INVALID_PARAMETER를 반환합니다.

지원 도구

현재 48개 도구에 공개 엔드포인트가 있습니다. 도구 페이지에서 매개변수를 확인하고 바로 실행할 수 있는 curl 요청을 복사하세요.

랜덤 농담랜덤 명언랜덤 질문랜덤 영어 단어랜덤 나라랜덤 도시랜덤 미국 주랜덤 대륙랜덤 여행지랜덤 언어랜덤 동물랜덤 원소랜덤 행성랜덤 천체랜덤 날씨랜덤 별자리체스 칸랜덤 계절랜덤 월랜덤 요일랜덤 방향뭐 먹지랜덤 음료랜덤 커피랜덤 디저트랜덤 활동랜덤 취미랜덤 직업랜덤 물건랜덤 연도랜덤 나이랜덤 생일랜덤 시간랜덤 각도랜덤 퍼센트랜덤 소수짝수·홀수랜덤 소수(素數)랜덤 좌표랜덤 2진수랜덤 숫자랜덤 색상랜덤 날짜랜덤 알파벳주사위동전 던지기예 또는 아니오가위바위보

응답

유틸리티 생성기는 통일된 응답 구조를 반환합니다:

{
  "tool": "random-number",
  "data": [
    { "value": "18" },
    { "value": "72" }
  ],
  "count": 2,
  "permalink": "https://randnext.com/random-number"
}

엄선 콘텐츠 엔드포인트는 더 자세한 출처 및 라이선스 필드도 반환합니다:

{
  "id": "qt_000001",
  "type": "quote",
  "text": "Well done is better than well said.",
  "author": "Benjamin Franklin",
  "category": "wisdom",
  "tags": [],
  "language": "en",
  "safety_level": "family",
  "source_url": null,
  "license": "public-domain",
  "attribution": "Poor Richard’s Almanack (1737)",
  "permalink": "https://randnext.com/random-quote?id=qt_000001"
}

attribution 값이 null이 아니면 콘텐츠 옆에 반드시 표시해야 합니다.

오류

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please try again later." } }
400INVALID_PARAMETER매개변수가 잘못되었습니다. 예: 알 수 없는 카테고리 또는 범위를 벗어난 limit.
401UNAUTHORIZED추첨 주최자 작업 전용: 관리 토큰이 없거나 올바르지 않습니다.
404NOT_FOUND알 수 없는 유형 또는 ID, 삭제된 항목이거나 필터와 일치하는 항목이 없습니다.
409CONFLICT추첨 주최자 작업 전용: 현재 추첨 상태에서는 이 작업을 수행할 수 없습니다.
429RATE_LIMITED요청이 너무 많습니다. Retry-After에 표시된 시간만큼 기다리세요.
500INTERNAL_ERROR서버에서 문제가 발생했습니다.
503SERVICE_UNAVAILABLE일시적으로 사용할 수 없거나 점검 중입니다.

제한 및 캐시

  • IP당 분당 60회, 하루 1,000회 요청할 수 있습니다. 모든 응답에 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 포함됩니다.
  • 랜덤 엔드포인트는 캐시하지 않습니다. ID 조회 응답과 완료된 추첨 기록은 최대 1시간 캐시될 수 있습니다.
  • 모든 출처의 GET 요청에 CORS가 열려 있습니다.

이용 약관

  • 무료로 사용하려면 randnext.com로 연결되는 “Powered by RandNext” 링크를 잘 보이게 표시해야 합니다.
  • attribution 필드가 있으면 항상 표시하세요.
  • 전체 콘텐츠 라이브러리를 다운로드해 재게시하거나 재판매하지 마세요.
  • SLA는 제공하지 않습니다. 제한을 변경하거나 악성 트래픽을 차단할 수 있습니다.

지원

공개 API는 현재 48개 도구를 지원합니다. 비밀번호, PIN, 비밀 토큰처럼 보안에 민감한 생성기는 브라우저에서만 실행되므로 생성된 비밀이 서버에 도달하지 않습니다. API 질문이나 문제 신고는 support@randnext.com로 엔드포인트와 응답 상태를 포함해 이메일을 보내세요.