API roadmap — 개발자 — Realistic Icon

개요

세 가지 연동 방식, 하나의 플랫폼.

Bluweo API는 스튜디오 웹 UI로 할 수 있는 모든 일을 서드파티 앱과 AI 에이전트가 프로그래밍 방식으로 쓸 수 있게 해줍니다. 3D 아이콘 라이브러리 검색, 프롬프트 기반 변형 생성, 다운로드 관리, 비동기 이벤트 수신까지 지원합니다.

REST API — 모든 HTTP 클라이언트를 위한 동기 호출.
MCP server — Claude, Cursor 등 MCP를 지원하는 모든 에이전트에 바로 꽂아 쓰는 도구.
Webhooks — 오래 걸리는 생성 작업과 결제 이벤트를 위한 비동기 푸시.

참고: API 접근은 다음에 포함됩니다: Studio 요금제. Free와 Designer 요금제는 웹 UI만 사용할 수 있습니다 — 아래 속도 제한을 참고하세요.

REST, MCP, 웹훅 — Bluweo 플랫폼에서 뻗어 나가는 세 가지 연동 방식.

빠른 시작

60초 안에 첫 호출까지.

계정을 만들고 Studio로 업그레이드하세요.
다음에서 API 키를 발급합니다: /dashboard/billing → API keys. 키는 다음으로 시작합니다: blu_live_.
모든 요청에 Bearer 토큰으로 담아 보내세요.
다음을 호출해 GET /v1/icons/search?q=fox 키가 동작하는지 확인하세요.

기본 URL: https://api.bluweo.com. 모든 요청은 HTTPS여야 합니다 — API는 평문 HTTP를 거부합니다.

# 1. Search the icon catalogue
curl https://api.bluweo.com/v1/icons/search?q=fox \
  -H "Authorization: Bearer blu_live_..."

인증

Bearer 키, 워크스페이스 단위.

모든 API 요청에는 다음이 필요합니다: Authorization: Bearer <key> 헤더가 필요합니다. 키는 대시보드에서 발급되며 하나의 워크스페이스에 묶입니다. 속도 제한은 키가 속한 등급에 따라 정해집니다.

키 형식: blu_live_* (운영) 또는 blu_test_* (샌드박스 — 과금 없음, 결과물에 워터마크).
한 번만 표시: 키는 서버에서 해시로 보관합니다. 분실하셨다면 교체해 주세요.
교체: 키는 다음으로 교체할 수 있습니다: POST /v1/keys/:id/roll; 이전을 돕기 위해 기존 키는 24시간 동안 계속 동작합니다.
폐기: DELETE /v1/keys/:id 즉시 적용됩니다.

REST API

검색, 생성, 다운로드, 관리.

모든 엔드포인트는 다음 아래에 있습니다: /v1/. JSON으로 보내고 JSON으로 받습니다. 필드는 스네이크 케이스, 타임스탬프는 UTC의 ISO-8601입니다.

메서드	경로	용도
GET	`/v1/icons`	아이콘 목록. 태그·스타일·색상으로 필터링.
GET	`/v1/icons/search`	카탈로그 전문 검색.
GET	`/v1/icons/:id`	아이콘 하나의 상세 정보와 변형.
POST	`/v1/icons/generate`	AI 생성을 시작합니다. 202를 반환합니다.
GET	`/v1/generations/:id`	생성 상태／결과물을 폴링합니다.
POST	`/v1/icons/:id/variants`	기존 아이콘에서 스타일／색상 변형을 만듭니다.
GET	`/v1/collections`	엄선한 컬렉션 목록.
POST	`/v1/downloads`	다운로드를 기록합니다（1 크레딧 차감）.
GET	`/v1/me`	워크스페이스 정보와 크레딧 잔액.
POST	`/v1/keys`	새 API 키를 발급합니다.
DELETE	`/v1/keys/:id`	키를 폐기합니다.

생성 작업은 비동기 입니다 — POST는 작업 ID와 함께 202를 반환하고, 실제 렌더링에는 5~30초가 걸립니다. 대기하지 말고 다음을 폴링하거나 /v1/generations/:id 다음을 구독하세요: generation.completed 웹훅을 사용하세요.

비동기 생성 흐름 — POST로 큐에 넣고, 워커가 처리하고, 웹훅이 알립니다.

# Generate a 3D icon
curl https://api.bluweo.com/v1/icons/generate \
  -X POST \
  -H "Authorization: Bearer blu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "cute 3D fox character, studio lighting",
    "kind": "icon",
    "aspect": "1:1",
    "outputs": 4
  }'

# → 202 { "id": "gen_01H...", "status": "queued" }

# Poll until done
curl https://api.bluweo.com/v1/generations/gen_01H... \
  -H "Authorization: Bearer blu_live_..."

MCP 서버

AI 에이전트가 Bluweo를 도구로 쓰게 하세요.

Model Context Protocol （MCP）는 AI 에이전트가 외부 도구를 호출할 수 있게 하는 Anthropic의 개방형 표준입니다. 저희 서버는 다음에서 운영합니다: /api/mcp （Streamable HTTP）. 이 URL을 Claude Code, Claude Desktop, Cursor 등 MCP를 지원하는 클라이언트에 추가하면, 에이전트가 대화 도중에 아이콘을 검색·미리보기·다운로드·생성할 수 있습니다. 설치할 것은 없습니다.

MCP 서버는 일곱 가지 도구를 제공합니다:

search_icons — 키워드／카테고리／스타일／컬렉션 검색.
get_icon — 상세 정보와 에이전트가 볼 수 있는 128px 미리보기.
list_collections — 엄선한 묶음 둘러보기.
get_account — 요금제, 크레딧, 다운로드 한도.
download_icon — 512px／원본 파일. 과금은 사이트와 완전히 동일합니다.
generate_icon — 프롬프트로 스튜디오에서 생성.
list_generations — 최근 스튜디오 실행 기록과 이미지 URL.

search_icons는 키 없이 쓸 수 있습니다(하루 100회). 나머지 도구에는 Studio 플랜의 개인 API 키가 필요하며, 다음으로 보냅니다: Authorization: Bearer blu_live_… — 설정 → API 키에서 만들 수 있습니다. MCP 가이드 읽기 →

MCP 흐름 — 에이전트가 도구를 호출하고, MCP 서버가 REST로 변환하고, 결과가 에이전트로 돌아갑니다.

# Claude Code — the Studio-plan key is required
claude mcp add --transport http realisticicon \
  https://realisticicon.com/api/mcp \
  --header "Authorization: Bearer blu_live_..."

웹훅

비동기 작업을 위한 푸시 알림.

대시보드에서 웹훅 URL을 설정하세요. 주목할 만한 일이 생길 때마다 서명된 JSON을 POST로 보내드립니다. 무엇보다 생성 상태를 폴링하지 않아도 되게 하기 위함입니다.

저희가 보내는 이벤트:

generation.completed — 결과물을 다운로드할 준비가 되었습니다.
generation.failed — 크레딧이 자동 환불됩니다. 페이로드에 실패 사유가 담깁니다.
credits.low — 잔액이 요금제 제공량의 20% 아래로 떨어졌습니다.
subscription.updated — 요금제가 변경／갱신／해지되었습니다.

모든 페이로드에는 다음 헤더가 들어 있습니다: Bluweo-Signature 본문을 여러분의 웹훅 시크릿으로 HMAC-SHA256 처리한 값입니다. 신뢰하기 전에 반드시 검증하세요; 서명이 없는 POST는 위조 요청일 수 있습니다.

# Example payload Bluweo POSTs to your endpoint
{
  "event": "generation.completed",
  "data": {
    "id": "gen_01H...",
    "status": "done",
    "outputs": [
      { "url": "https://cdn.bluweo.com/g/.../0.png", "width": 1024, "height": 1024 }
    ],
    "credits_used": 5
  },
  "created_at": "2026-05-16T17:42:11Z"
}

# Header attached:
# Bluweo-Signature: t=1715882531,v1=<hmac>

속도 제한과 할당량

키 단위·월 단위, 그리고 공정성을 위한 초 단위 제한까지.

모든 키에는 두 가지 제한이 적용됩니다: 월간 사용량 （요금제별 할당량）과 단시간 버스트 （공용 자원 보호를 위해 초당 10회）입니다. 둘 다 모든 응답에 표준 X-RateLimit-* 헤더로 함께 반환됩니다.

요금제	API 접근	월 할당량	버스트
Free	—（웹 UI 전용）	—	—
Designer	—（웹 UI 전용）	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

생성과 다운로드는 또한 요금제 제공량의 크레딧도 사용합니다 — 자세한 내용은 요금제. 크레딧 팩 충전으로 API 할당량이 늘어나지는 않습니다. 생성 비용만 충당합니다.

제한을 초과하면 다음을 반환합니다: 429 Too Many Requests 함께 다음 헤더가 붙습니다: Retry-After 그 시간만큼 요청을 멈췄다가 다시 시도하세요 — 물러서는 데 따른 불이익은 없습니다.

요금제별 API 접근 — Free와 Designer는 웹 UI만, Studio는 API까지.

# Every response includes:
X-RateLimit-Limit:        10000
X-RateLimit-Remaining:    9847
X-RateLimit-Reset:        1715958000   # unix epoch
X-RateLimit-Burst-Limit:  10
X-RateLimit-Burst-Remaining: 7

# On 429:
Retry-After: 3            # seconds

오류

일반적인 HTTP 상태 코드 + 구조화된 JSON 본문.

자주 쓰이는 상태 코드:

코드	의미
`200`	OK — 동기 호출 성공.
`202`	Accepted — 비동기 작업이 큐에 들어갔습니다.
`400`	요청 본문이나 쿼리 파라미터가 잘못되었습니다.
`401`	API 키가 없거나 유효하지 않습니다.
`402`	크레딧 부족 — 충전 후 다시 시도하세요.
`403`	키는 유효하지만 요금제 등급에 API 접근 권한이 없습니다.
`404`	리소스를 찾을 수 없습니다.
`409`	상태 충돌（예: 이미 폐기된 키를 다시 폐기）.
`429`	속도 제한에 걸렸습니다 — 다음을 참고하세요: `Retry-After`.
`5xx`	저희 쪽 문제입니다. 멱등한 요청은 자동으로 재시도하며, 직접 다시 시도하셔도 안전합니다.

모든 오류 본문은 JSON입니다: { "error": { "code", "message", "request_id" } }. 문의하실 때 다음을 함께 알려주세요: request_id 추적 기록을 확인할 수 있습니다.

# 402 — out of credits
{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 3 credits; generate(outputs=4) requires 20.",
    "request_id": "req_01H9R..."
  }
}

# 429 — rate limit
{
  "error": {
    "code": "rate_limited",
    "message": "Burst limit of 10 req/s exceeded.",
    "request_id": "req_01H9R..."
  }
}

제약 사항

지금은 API로 할 수 없는 일 — 미리 알려드립니다.

오프라인／온프레미스는 지원하지 않습니다. 생성은 항상 저희 인프라에서 실행됩니다. 아이콘 라이브러리는 클라이언트에 캐시할 수 있지만 AI 생성은 불가능합니다.
한 번의 호출로 일괄 생성은 지원하지 않습니다. 각 POST /v1/icons/generate 호출은 프롬프트 1개 × 최대 4개의 결과물을 처리합니다. 더 큰 배치는 직접 병렬로 나눠 보내세요. 버스트 제한은 그대로 적용됩니다.
프롬프트 최대 길이: 1,000자. 더 긴 프롬프트는 400으로 거부됩니다.
결과물 해상도는 2048 × 2048까지입니다. 그 이상의 해상도는 별도 계약이 필요합니다.
생성 소요 시간: 5~30초. 최악의 경우（큐 포화）에는 최대 2분까지 걸립니다. 비동기를 전제로 설계하시고, 촘촘한 폴링 대신 웹훅을 사용하세요.
MCP 전송: Streamable HTTP만 지원. 로컬 stdio(npx) 패키지는 아직 없습니다 — 호스팅된 URL에 연결하세요.
Studio 등급에는 SLA가 없습니다. Enterprise 계약에는 99.9% 가동률과 전담 지원이 포함됩니다. 문의하기.

이 목록으로 부족한 것이 있으신가요?

Enterprise 요금제에서 열리는 것들:

맞춤 해상도와, 자사 브랜드 자산 기반의 스타일 파인튜닝.
전용 처리 용량（공유 큐 없음）.
VPC／온프레미스 배포.
전담 지원 + 99.9% SLA.
월 1만 건을 넘는 경우의 대량 요금.

영업팀에 문의 →

버전 관리

v1 이(가) 현재 버전입니다. 호환성을 깨는 변경은 다음으로 배포합니다: v2.

버전은 URL 경로에 들어갑니다: /v1/.... 같은 버전 안에서는 추가만 하는 변경만 합니다 — 새 필드, 새 엔드포인트, 새 이벤트 유형. 같은 버전 안에서 필드를 없애거나 타입을 바꾸는 일은 절대 없습니다.

다음을 배포하면 v2, v1 이전 버전은 최소 다음 기간 동안 계속 운영됩니다: 12개월 지원 종료일은 다음 엔드포인트로 공지하며 changelog 모든 API 사용자에게 이메일로도 알려드립니다.

변경 이력: GET /v1/changelog 출시 이후의 모든 변경 사항을 최신순으로 반환합니다.
상태 페이지: status.bluweo.com 실시간 가동률과 장애 이력을 확인할 수 있습니다.
이메일 알림: 대시보드에서 신청하세요. 호환성을 깨는 변경 예고와 중대한 장애에 대해서만 발송합니다.

# Read the changelog (no auth needed)
curl https://api.bluweo.com/v1/changelog | jq

# Sample entry:
{
  "version": "1.4.0",
  "released_at": "2026-04-22",
  "title": "MCP tools: list_collections + variant generation",
  "highlights": [
    "New MCP tool: list_collections",
    "Variant generation now supports color hex shorthand",
    "Webhook signatures use t=...,v1=... format (v0 deprecated 2026-10-22)"
  ]
}

개발을 시작할 준비가 되셨나요?

대시보드에서 첫 API 키를 발급받으세요. 맞춤 계약이 필요하시면 문의해 주세요.

Studio로 업그레이드 영업팀에 문의