본문으로 건너뛰기

변경 기록

임베드 SDK, 플랫폼 API 및 이 문서의 주요 변경 사항입니다. SDK는 /embed/v1/*에서, API는 /inference-api/b2b/v1/*에서 버전을 관리합니다. 호환되지 않는 변경은 이전 버전과 함께 새로운 주 버전으로 배포됩니다(CDN 버전 관리). 새로운 스트림 이벤트나 응답 필드 같은 추가 변경은 버전을 변경하지 않고 제공되므로 클라이언트는 알 수 없는 항목을 무시해야 합니다.

2026-10-21: Viewer 채팅 바, 지도 자체의 장소로 답변하는 기능 활성화​

  • 페이지용 채팅 바. <kaleidr-map product="viewer" layout="bar">는 방문자의 질문으로 게시된 지도를 여는 질문 입력란 하나입니다. 기본적으로 페이지 위에 열리며, results-url을 지정하면 내 페이지에서 열립니다. 제목, 자리표시자, 예시 질문, 강조 색상, 테마, 언어는 속성으로 지정합니다. 채팅 바를 참고하세요.
  • Viewer가 질문과 함께 열릴 수 있습니다. prompt(페이지 URL에서 읽으려면 prompt-param)와 iframe의 q 매개변수는 지도가 열릴 때 지도의 Kaleidr AI에 질문을 던지며, handle.send()는 코드에서 질문합니다. 추가 변경이므로 버전은 바뀌지 않습니다.
  • 지도 자체의 장소로 답변하는 기능이 켜졌습니다. 게시된 지도나 공유 링크의 Ask Kaleidr 패널은 지도에 표시된 이름 있는 장소를 먼저 사용하여 답합니다. 지도 자체의 장소로 답변하기를 참고하세요.
  • 템플릿 스토어가 코드를 작성합니다. template.kaleidr.com에서 선택한 지도에 맞는 두 스니펫을 모두 만들어 줍니다. 다운로드형 웹사이트 템플릿은 지원이 종료되었습니다.

2026-10-18: 공유 링크의 Kaleidr AI는 지도가 게시되어 있어야 함​

  • 지도 게시를 취소하면 공유 링크의 Kaleidr AI가 중단됩니다. 또한 링크 스냅샷이 아니라 지도의 현재 허용 도메인에 포함된 페이지에서만 작동합니다. 지도 게시를 취소하거나 페이지 도메인을 제거하면 게시된 지도와 마찬가지로 5분 이내에 중단되며, 다시 게시하면 복원됩니다. Control Tower 및 Popup Window 스위치는 계속 스냅샷을 따르며, 링크 자체는 지도를 계속 보여 줍니다. 지도의 게시가 취소된 공유 링크에 대해 POST /sdk/share-sessions는 404 not_found를 반환합니다. 게시된 지도의 Kaleidr AI를 참조하세요.

2026-10-16: 게시된 지도의 Kaleidr AI가 지도 자체의 스위치를 따름​

  • 지도의 Kaleidr AI 타일이 유일한 스위치입니다. Studio에서 Control Tower는 게시된 지도의 방문자에게 Ask Kaleidr 패널을, Popup Window는 팝업의 AI 채팅을 제공하며 iframe과 Viewer 요소 모두에 적용됩니다. Share의 Embed에 있던 Visitor AI Chat 스위치는 없어졌습니다. 게시된 지도의 Kaleidr AI를 참고하세요.
  • 지도별 월간 한도가 없어졌습니다. Monthly AI Credit Limit 입력란이 없어졌습니다. 방문자는 요금제 할당량까지 소유자의 AI 크레딧을 사용하며, 방문자별 및 지도별 요청 속도 제한은 변경되지 않았습니다.
  • POST /sdk/share-sessions가 feature를 받습니다. control_tower(기본값) 또는 popups이며, 각 기능은 해당 스위치가 켜져 있을 때만 허용되고 그렇지 않으면 403 chat_disabled가 반환됩니다. POST /sdk/share-sessions를 참고하세요.
  • 공유 링크에서도 Kaleidr AI가 열립니다. 공유 링크의 ID는 링크의 스냅샷, 즉 링크를 만들 당시의 Control Tower 및 Popup Window 스위치와 허용 도메인에 따라 허용되며 비용은 지도 소유자가 부담합니다. Studio에서 Kaleidr AI를 꺼도 이미 전달된 공유 링크에서는 꺼지지 않습니다. 알 수 없는 ID는 여전히 404 not_found가 반환됩니다.
  • Viewer와 Tile은 Studio처럼 스크롤로 확대/축소됩니다. 포인터가 지도 위에 있을 때 스크롤하면 Ctrl이나 ⌘ 없이 지도가 확대/축소되고, 포인터가 지도 밖에 있으면 스크롤은 페이지를 이동합니다. iframe의 gestures=greedy 매개변수는 더 이상 읽지 않습니다.

2026-10-14: 특정 지점의 정보와 사용 중단 예정 엔드포인트 두 개​

  • 신규: POST /spot 및 POST /spot/overview/stream. /spot은 지정한 지점에 무엇이 있는지 반환합니다. 클릭한 장소, 가장 가까운 도로명 주소, 해당 지점이 속한 지역과 함께 각 값에 표시해야 할 출처를 제공합니다. 요청하면 장소 설명과 사진도 포함합니다. /spot/overview/stream은 반환된 항목 하나의 개요를 스트리밍하며, 그 앞에 장소의 전체 이름을 담은 place 프레임을 보냅니다. POST /spot을 참고하세요.
  • /spot은 호출을 위해 콘텐츠를 가져올 때만 콘텐츠 요금을 부과합니다. 이전 요청에서 이미 가져온 콘텐츠는 요금이 없으므로, /spot 콘텐츠 조회 요금은 /retrieval/poi/enrich와 같거나 더 낮습니다.
  • 지원 중단 예정: GET /retrieval/poi/enrich 및 POST /chat/summary/stream. 2027-01-15까지 기존처럼 응답하며 이후 언제든 제거될 수 있습니다. 응답 헤더에는 Deprecation, Sunset, 대체 API를 가리키는 Link가 포함됩니다. 지원 중단 API에서 이전하기를 참고하세요.
  • tenants를 반환합니다. /spot은 건물 내 업체를 숨기지 않고 CDLA-Permissive-2.0에 따라 poi: 참조가 있는 tenant 엔터티로 반환합니다. 이 조회는 계속 무료입니다.
  • 모든 요약에 과금합니다. 장소 요약 및 개요는 요청할 때마다 사용된 토큰에 따라 과금되며, start 및 end 이벤트의 cached 필드는 더 이상 전송되지 않습니다.
  • 건물 요약을 대체할 기능은 없습니다. 건물 개요는 API로 제공되지 않습니다. API에서 반환하지 않는 내용을 참고하세요. /spot/overview/stream은 ID가 없는 building:도 받아들이며, building:<id>와 마찬가지로 error 프레임 하나로 응답합니다.

2026-10-13: 제품 변경 사항과 수정·확장된 문서​

이 항목은 두 부분으로 구성됩니다. 제품 변경 사항과 API 제한 및 요청 거부는 이번 릴리스에서 제품이 변경된 내용을 설명합니다. 문서 수정 사항은 실제 제품에서 제공하지 않는 기능을 문서에서 설명한 부분을 정리합니다. 각 페이지를 SDK와 API에 맞춰 한 줄씩 확인한 뒤 수정하고 내용을 확장했습니다. 이전 문서를 기반으로 개발했다면 수정 사항을 확인하세요.

제품 변경 사항​

  • 업체 데이터는 Kaleidr Studio에서 업로드합니다. 모든 지도의 데이터 패널 맨 아래에 있는 Data for AI Answers 섹션이 업로드 화면입니다. .csv 또는 .json 파일을 선택하고 CSV 열 매핑을 제안받아 검토한 뒤 미리 보기, 게시를 거쳐 Releases 목록에서 결과를 확인합니다. 업로드 화면은 이곳뿐이며 업로드 권한이 있는 조직의 소유자와 관리자에게만 표시됩니다. 변경되지 않은 업로드 API와 동일한 처리 과정을 사용합니다. Enterprise에서 다른 요금제로 전환했지만 릴리스가 남아 있는 조직에서는 소유자와 관리자에게 '업로드는 Enterprise 요금제에 포함됩니다.'라는 문구와 Releases 목록이 계속 표시됩니다. 그 외 Enterprise 미만 조직에는 이 섹션이 나타나지 않습니다. 자체 데이터로 답변하기 및 업로드할 수 없을 때의 표시를 참고하세요.
  • 업체 데이터 업로드와 답변 활용은 Enterprise 전용입니다. Enterprise 조직의 소유자 또는 관리자는 데이터를 업로드하고 게시할 수 있습니다. Kaleidr Studio 도우미는 조직이 Enterprise를 이용하는 동안에만 로그인한 조직 구성원에게 이 데이터에 기반한 답변을 제공합니다. Free와 Pro에서는 업체 데이터를 업로드할 수 없습니다. 장소 수, 문서 수, 파일 크기 제한은 조직별 계약에서 정하며 플랫폼의 최대 한도를 넘지 않습니다. 제한을 초과하면 한도와 요금제가 사유에 포함된 422 응답이 반환됩니다. 적용되는 요금제는 kaleidr.com/billing에서 조직이 구매하거나 변경한 Kaleidr 요금제입니다. API 키 또는 SDK를 통해 읽으려면 Enterprise 전용인 vendor 범위도 필요합니다. 요금제별 제공 여부를 참고하세요.
  • 지도 데이터 세트의 한도는 요금제별로 다릅니다. 로그인 사용자가 Kaleidr Studio 데이터 패널에서 지도에 추가하는 파일은 모든 요금제에서 사용할 수 있지만 제한이 있습니다. Free는 데이터 세트당 50,000행, 파일당 32 MiB, 조직의 전체 데이터 세트에서 250,000행이며, Pro는 각각 100,000행, 64 MiB, 5,000,000행입니다. Enterprise의 세트당·파일당 최대치는 Pro와 같고 조직 전체 한도는 계약에 따릅니다. 요금제 제한을 초과하면 새로운 업로드만 HTTP 402 quota_exceeded로 거부되고 기존 데이터는 유지됩니다. Enterprise를 포함한 모든 요금제에는 네 가지 공통 최대치도 적용되며 이를 넘으면 402 대신 HTTP 400 VALIDATION_ERROR가 반환됩니다. 파일 64 MiB 초과, 데이터 세트 100,000행 초과, 지리 파일 50,000개 피처 초과, 이미지 오버레이 16 MiB 초과입니다(GeoTIFF 원본이 아닌 Studio가 GeoTIFF에서 만든 이미지). Studio 업로더에 붙여 넣은 JSON은 모든 사용자에 대해 지도 자체에 저장되며 이 제한에 포함되지 않습니다. 지도 데이터 세트 및 오류를 참고하세요.
  • 거부된 데이터 세트 업로드는 지도에 아무것도 추가하지 않습니다. Studio는 서버의 모든 거부 사유를 업로드 컨트롤 옆에 표시하고 파일을 추가하지 않습니다. 요금제 제한(402, 서버 메시지와 Upgrade Plan 링크), 로그아웃된 세션, 권한 없음, 지나치게 큰 파일, 과도한 업로드, 공통 최대치 위반 시의 400 등 모든 거부가 포함됩니다. 서버가 응답하지 않거나 시간 초과 또는 장애가 발생한 경우에만, 표가 요금제 제한 내에 있으면 경고를 표시하며 행을 지도 자체에 저장할 수 있습니다. 그렇지 않으면 아무것도 추가하지 않습니다. 업로드 실패 시를 참고하세요.
  • 데이터 패널에서 데이터 세트를 삭제하면 영구 삭제됩니다. 저장된 세트의 휴지통 컨트롤은 확인을 요청한 뒤 세트를 삭제하고 지도와 레이어에서 제거하며 조직 전체 행 제한에서 사용량을 해제합니다. 게시된 지도와 공유 링크에서도 더 이상 제공되지 않습니다. 같은 이름의 파일을 업로드하면 새 세트가 저장된 뒤 이전 세트를 대체합니다. 새 파일을 읽지 못하면 지도는 이전 데이터로 돌아가고 Studio가 알립니다. 실행 취소로 삭제된 세트에 대한 지도 참조를 되돌릴 수 있지만, 해당 레이어는 그려지지 않습니다. 데이터 세트 삭제 또는 교체를 참고하세요.
  • Studio의 제한은 조직의 Kaleidr 요금제를 따릅니다. 조직이 보관할 수 있는 지도 수와 위 데이터 세트 한도는 kaleidr.com/billing에서 구매·변경한 요금제에 따릅니다. Kaleidr Studio에는 별도 요금제가 없습니다.
  • 게시된 지도와 공유 링크는 지도에 업로드한 데이터를 표시합니다. Studio 데이터 패널에서 추가한 데이터 세트는 레이어로 그려지고 이미지 오버레이도 내장 뷰어와 공유 링크에 표시됩니다. 게시된 지도에 포함된 데이터만 제공됩니다. 데이터 패널에서 세트를 삭제하면 게시된 지도 및 이를 그리던 모든 공유 링크에서 제공이 중단됩니다. 지도 게시를 해제하면 내장 지도가 중지되지만 이미 배포한 공유 링크는 기존 데이터로 계속 동작합니다. 브라우저는 이미 로드한 데이터를 유지하며 발급된 다운로드 링크는 최대 한 시간 동안 접근 가능할 수 있습니다. 방문자는 모든 열이 포함된 전체 데이터 세트를 다운로드하므로 큰 표는 로딩이 느려지고 게시된 데이터 세트는 공개 상태입니다. 게시 지도에 업로드된 데이터를 참고하세요.
  • Studio에서 게시한 지도를 게시 취소할 수 있습니다. 게시 중인 지도는 Publish & embed 화면에 확인이 필요한 Unpublish 버튼이 나타납니다. 이후 모든 내장 지도에는 사용할 수 없다는 메시지가 표시됩니다. 지도 ID는 유지되므로 다시 게시하면 같은 내장 URL이 복구됩니다. 지도 게시 취소를 참고하세요.
  • Studio AI 도우미는 전체 데이터 세트에 대해 답변합니다. 열린 지도에서는 업로드된 세트의 샘플이 아닌 전체 행에 대해 필터링, 정렬, 개수, 합계, 평균, 그룹화, 특정 점 근처나 영역 내부 행 찾기를 수행합니다. 한 번에 한 세트를 사용하며 결과에 최대 100개 행 또는 그룹을 표시합니다. 데이터를 읽기만 하고 변경하지 않습니다. 데이터 세트에 대해 질문하기를 참고하세요.
  • 데이터 세트에는 열 역할이 있습니다. 업로드 후 Studio가 이름, 카테고리, 설명, 주소 열을 감지하며 제작자는 데이터 패널의 세트별 Column Roles 항목에서 수정할 수 있습니다. 이름 열은 Studio AI 도우미와 게시 지도 채팅에서 각 장소를 부르는 이름이 됩니다. Studio에서 같은 이름의 파일을 업로드하면 새 세트가 저장되고, 같은 열이 있으면 이전 역할을 이어받습니다. 열 역할을 참고하세요.
  • 지도 자체 장소 기반 답변을 켠 경우 Visitor AI Chat이 게시 지도의 업로드된 데이터 세트로 답변할 수 있습니다. 이 동작은 Kaleidr가 플랫폼 전체에 대해 설정하며 기본값은 꺼짐입니다. 켜져 있으면 채팅이 읽는 장소에 게시 지도에 포함된 데이터 세트의 행도 포함됩니다. 데이터 세트에 이름 열이 있고 행에 점 좌표가 있어야 하며 지도당 최대 200개 장소 제한이 적용됩니다. 지도의 장소로부터 답변하기를 참고하세요.
  • 조직이 업로드할 수 있는 항목을 보고하는 호출이 추가되었습니다. GET /shared-api/datahub/limits는 업체 데이터 업로드 가능 여부와 조직 요금제 및 한도를 반환합니다. 모든 요금제에서 200이며 Enterprise 미만은 can_upload: false를 반환합니다. Studio 섹션에도 같은 한도가 한 줄로 나타납니다. 조직의 업로드 가능 범위를 참고하세요.
  • 업로드할 수 없는 요금제의 거부 코드는 403 vendor_data_not_on_plan입니다. 이전 문서의 코드를 대체하며 예전 코드는 더 이상 반환되지 않습니다. 이전 코드를 확인하는 클라이언트를 수정하세요.
  • 릴리스를 게시 취소하고 삭제할 수 있습니다. POST /shared-api/datahub/releases/{id}/unpublish는 게시 릴리스를 즉시 중단하며 DELETE /shared-api/datahub/releases/{id}는 게시되지 않은 릴리스와 그로부터 생성된 모든 항목을 제거합니다. 요금제를 낮춘 뒤에도 모든 요금제에서 조직 소유자 또는 관리자가 이용할 수 있습니다. Studio Releases 목록에는 Unpublish와 Delete가 있으며 Enterprise를 떠났어도 릴리스를 보유한 조직의 관리자에게 제공됩니다. 목록에는 state, ingest_id가 추가되었습니다. 릴리스 회수를 참고하세요.
  • 오래된 릴리스는 자동 삭제됩니다. 교체, 게시 취소 또는 만료된 미리 보기 릴리스는 현재 상태에서 벗어난 지 30일 후 삭제됩니다. 실패한 릴리스는 마지막 처리 시도 30일 후 삭제됩니다. 릴리스 보관 기간을 참고하세요.
  • 열 매핑 제안에는 AI 크레딧이 사용됩니다. POST /inference-api/vendor/mapping/propose는 조직 AI 크레딧으로 과금하며 크레딧이 소진되면 429 quota_exceeded를 반환합니다. 계정당 시간당 30개 제안 제한은 그대로이며 두 종류의 429는 응답 본문이 다릅니다. 두 429 구별하기를 참고하세요.
  • vendor 범위는 Enterprise 전용입니다. Free 및 Pro 키에는 포함할 수 없습니다. Free 또는 Pro에서 vendor를 요청하면 403 tier_capability_not_allowed가 반환됩니다. 이전에는 Free가 범위를 조용히 제거했고 Pro는 그런 키를 만들 수 있었습니다. Enterprise 미만에서 vendor가 있던 키를 교체하면 새 키에서는 범위가 빠집니다. Enterprise에서 하향 변경하면 기존 키는 오류 없이 데이터 접근을 잃고 이미 열린 브라우저 세션도 종료됩니다. Pro에서는 서버 키와 더 많은 활성 키를 계속 사용할 수 있습니다. 인증과 범위를 참고하세요.
  • Chat에 언어, 제목, 입력 안내 문구를 지정할 수 있습니다. 새로운 마운트 옵션은 lang, title, placeholder이며 요소 속성은 lang, chat-title, placeholder입니다. lang이 없으면 페이지의 유효한 <html lang>을 사용하고 그렇지 않으면 영어를 사용합니다. Chat 참고를 참고하세요.
  • <kaleidr-map>은 기본적으로 블록 요소입니다. 별도 CSS가 없으면 display:block이므로 height가 적용됩니다. 이전에는 display:block을 따로 설정하지 않으면 높이가 적용되지 않았습니다. Safari 16.4 이전을 지원하기 위해 예제에는 display:block이 계속 포함됩니다. 크기 설정을 참고하세요.
  • 마운트 직후 실행한 핸들 호출이 보관됩니다. Viewer와 Tile에서 프레임 내부 지도가 준비되기 전 실행한 setCamera(Tile은 setStyle도 포함)는 지도가 준비되면 적용되며 최신 256개 호출까지 보관합니다. 이전에는 호출이 사라졌습니다. 프레임 로드 후 보통 10초의 제한된 대기 시간이 지나도 준비 완료 신호가 없으면 보관된 호출을 실행하고 콘솔 경고를 한 번 남깁니다. 이제 핸들을 쓰기 전에 kaleidr-embed:ready를 기다릴 필요가 없습니다.
  • CDN 기본 주소 재정의는 세 종류의 출처만 허용합니다. base 옵션과 속성, window.__KALEIDR_EMBED_BASE__는 Kaleidr CDN(https://cdn.kaleidr.com), kaleidr.js를 로드한 출처 또는 페이지 자체 출처일 때만 적용됩니다. 다른 값은 콘솔 경고와 함께 무시되고 기본 CDN을 사용합니다. 로더와 번들을 같은 출처에서 제공하면 자체 호스팅도 가능합니다. CDN 버전 관리를 참고하세요.
  • 제품 스크립트는 모든 페이지에서 UTF-8로 로드됩니다. 페이지가 선언한 문자 인코딩과 관계없이 로더가 UTF-8을 사용합니다. 이전에는 인코딩을 선언하지 않은 페이지에서 Chat 또는 Editor가 마운트되지 않고 콘솔에 chat.js loaded but window.KaleidrGeoChat is missing가 표시될 수 있었습니다. 문제 해결을 참고하세요.
  • destroy() 후 같은 요소에 다시 마운트해도 안전합니다. React Strict Mode처럼 첫 마운트가 아직 로딩 중일 때도 마찬가지입니다.
  • 거부된 요청은 크레딧을 점유하지 않습니다. 속도나 동시 실행 제한, 유효성 오류, 너무 큰 본문 등으로 처리 전에 거부된 요청은 AI 크레딧이나 동시 실행 슬롯을 남기지 않습니다. 할당량 및 속도 제한을 참고하세요.
  • Viewer와 Tile에서는 페이지가 지정한 카메라가 우선합니다. 로드 시 전달한 center, zoom, pitch, bearing, iframe URL의 camera 또는 setCamera는 화면 너비와 콘텐츠 구도에 따라 작성자가 저장한 뷰보다 우선하며 크기 변경 시 자동 재구도도 종료합니다. 페이지가 지정하지 않은 값은 작성자의 설정을 유지하고, center 없이 로드 시 전달된 zoom은 무시됩니다. 카메라를 참고하세요.
  • Viewer 또는 Tile 요소의 Chat은 핀을 유지합니다. 다른 지도와 마찬가지로 여러 답변에 걸쳐 핀이 누적되고 같은 장소가 새 좌표로 등장하면 핀을 추가하지 않고 기존 핀을 이동합니다. 채팅을 닫거나 제거하면 핀, 경로 및 기타 그린 요소가 삭제됩니다. 기능 및 제한을 참고하세요.
  • Chat의 title은 패널 제목입니다. 전달한 제목은 각 대화가 시작되면 채팅 창 머리글에 표시됩니다. 이전에는 대화에서 생성한 제목으로 대체되었습니다. 최소화된 채팅에는 자체 대화의 제목이 나타납니다. 제목과 입력 안내 문구를 참고하세요.
  • Editor는 게시 가능 키로 기본 지도 요청을 식별합니다. kaleidr.js로 마운트한 Editor는 스타일, 스프라이트, 글꼴을 https://tile.kaleidr.com에서 요청할 때 페이지의 게시 가능 키를 함께 전송합니다. 세션 토큰은 URL에 넣지 않습니다. 새로운 옵션은 없습니다. 페이지에서 실행되는 항목을 참고하세요.

API 제한 및 거부​

  • Chat 스트림 요청에는 전용 코드가 있는 제한이 있습니다. 422 too_many_messages, message_too_long, conversation_too_long, invalid_session_id, lang_too_long입니다. 엔드포인트를 참고하세요.
  • 요약 및 버튼 스트림 은 너무 긴 필드를 422 field_too_long으로 거부합니다.
  • 2 MiB를 초과하는 요청 본문(디자인 엔드포인트는 5 MiB)은 413 request_too_large로 거부합니다.
  • 완료 전에 종료된 Chat 스트림 은 전송된 대화 크기 이상으로 과금됩니다.
  • 세션 토큰이 볼 수 있는 정보는 적습니다. 세션 토큰의 429 quota_exceeded 응답 본문과 quota 이벤트에는 요금제, 사용량 또는 한도가 없습니다.
  • 서버 키 또는 레거시 키의 제품 제한 은 요청마다 403 product_not_allowed로 적용됩니다.
  • 업체 데이터 업로드 에 필드·목록별 제한, 413 request_body_too_large, 409 org_ingest_in_progress, 429 ingest_rate_limited가 추가됐습니다. 열 매핑 제안 호출은 업로드할 수 있는 Enterprise 조직의 소유자 또는 관리자만 할 수 있습니다. 업체 데이터 업로드를 참고하세요.
  • Kaleidr Studio 데이터 세트 업로드 가 요금제 제한을 넘으면 402 quota_exceeded, 모든 요금제의 절대 상한을 넘으면 400 VALIDATION_ERROR입니다. 오류를 참고하세요.

이 페이지의 수정 사항​

아래 각 항목은 제품은 변경되지 않았지만 기존 문서의 내용이 잘못되었던 부분입니다.

오류 코드 및 상태

  • AI 크레딧을 초과한 요청은 "error": "quota_exceeded"를 포함한 429를 반환합니다. 이전 문서의 b2b.tokens_exceeded는 API가 반환한 적 없는 코드입니다. 문서화된 응답 본문에 detail, product, period도 빠져 있었습니다.
  • map_load_hard_stop 코드는 없습니다. 아래 '요금제'를 참고하세요.
  • 허용 출처 목록에 없는 출처에서 세션을 교환하면 403 origin_not_allowed가 반환됩니다. 예전의 session_origin_mismatch 표기는 잘못됐으며 이는 토큰 발급 출처와 다른 곳에서 사용할 때의 코드입니다.
  • vendor_scope_requires_acknowledgement는 403이 아닌 422이고 게시 가능 키에만 적용됩니다.
  • sessions_disabled는 404, sessions_not_configured는 503입니다. 이전에는 둘 다 403이었습니다.
  • 401 응답에는 {"detail": "Invalid or missing API key"}가 포함됩니다. 이전에는 본문이 없다고 설명했습니다.
  • map_load_quota_exceeded는 {"detail": "map_load_quota_exceeded"} 형태로 반환됩니다. 예전의 평면 본문 예시는 존재하지 않습니다.
  • 키 서비스 장애는 503이 아닌 401을 반환합니다.
  • Viewer 임베드에 키를 넘겨도 product_not_allowed가 발생하지 않습니다. Viewer에는 키가 필요 없습니다.
  • 기존에 빠져 있던 visitor_limit_reached, chat_disabled, not_found, owner_has_no_organization, org_admin_required, key_not_found, key_already_rotated 등이 추가됐습니다.
  • 편집 시의 key_already_rotated와 key_expired 는 expires_at에만 적용되며, 키의 다른 필드는 계속 편집할 수 있습니다. 이미 취소한 키를 다시 취소하면 200입니다.
  • 거부 코드의 위치. 403 또는 404는 detail에 코드를 넣습니다. 플랫폼 API의 429는 error에 코드, detail에 설명을 넣습니다. 예외인 map_load_quota_exceeded는 detail에 들어갑니다. 업로드 API의 429는 응답 형식을 참고하세요.

전체 목록은 오류를 참조하세요.

요금제, 할당량 및 키

  • 자체 데이터에 기반한 답변 은 예전에 'Pro부터' 가능하다고 설명됐습니다. 실제 업체 데이터를 활용하는 AI 답변은 업로드와 API/SDK의 vendor 읽기 범위 모두 Enterprise 전용입니다. Free와 Pro에는 Studio 지도에 데이터 세트를 추가하는 별도 기능이 있습니다. 위 '제품 변경 사항'을 참고하세요.
  • 지도 로드는 모든 요금제에서 할당량에 도달하면 중단됩니다. 유료 요금제에서 할당량의 다섯 배까지 사용할 수 있다는 기존 설명은 틀렸습니다. 지도 로드 팩을 구매하면 한도가 증가합니다.
  • AI 크레딧은 조직마다 하나의 공동 잔액 으로, API 키와 팀의 Kaleidr 앱 사용이 함께 차감됩니다. 별도의 월간 API 토큰 예산이라는 설명은 잘못됐습니다.
  • 할당량 기간은 결제 주기 로, 항상 달력상의 월은 아닙니다.
  • 속도 제한은 키별 이며 동시 실행은 조직별입니다. 키가 속도 제한을 공유한다는 설명은 틀렸습니다.
  • 게시 가능 키의 허용 출처 목록은 선택 사항 입니다. 라이브 키에는 출처가 하나 이상 필요하다는 이전 설명과 달리 빈 목록은 모든 출처를 허용합니다.
  • 키 생성 후에는 범위를 수정할 수 없습니다. 편집하거나 제거할 수 있다는 기존 문서는 잘못됐습니다. 새 키를 만들고 기존 키를 취소해야 합니다.
  • 서버 키와 레거시 키는 런타임 요청에 직접 전송합니다. 모든 요청에 세션 토큰을 사용한다는 설명은 틀렸습니다.
  • Free에서 키 회전. Free에서 게시 가능 키를 회전하면 기존 설정과 무관하게 Free의 모든 기능(ai, maps, design, 네 가지 제품)을 받습니다. Free의 서버 키나 레거시 키 회전은 403 free_plan_publishable_only로 거부됩니다.
  • monthly_cap_tokens: 1 이상이면 한도가 설정되며 0 또는 null은 제한 없음입니다.
  • 키 생성 시 org_id 는 JSON 본문에 넣습니다. 쿼리 org_id는 다른 키 API에서만 읽습니다.
  • Visitor AI Chat은 모든 요청을 계산합니다. 질문 하나마다 답변 요청 1개, 결과 카드마다 사진 요청 1개가 발생합니다. 카드 열기, 후속 질문, 경로 안내에서 주소 검색, 경로 계산도 각각 별도 요청이며 모두 방문자별 제한에 포함됩니다. 게시 지도에서 채팅 사용을 참고하세요.

할당량 및 속도 제한과 인증 및 범위를 참조하세요.

스트리밍

  • quota 이벤트는 end 또는 error 뒤에 오는 스트림의 마지막 이벤트 입니다. 중간에 전달된다는 이전 설명은 틀렸습니다. 사용량을 알려줄 뿐 종료 전에 경고하지 못합니다.
  • place 이벤트는 좌표 없이 도착하고 unverified: true로 표시될 수 있습니다.
  • error 이벤트의 code는 upstream_stall인 한 경우에만 들어 있습니다.
  • 스트림이 전송하는 카드·레이어 이벤트(weather_card, building_card, arrivals_card 등)가 목록에 추가됐습니다.
  • 요약 및 버튼 스트림의 사양이 추가됐습니다.
  • 세션 토큰의 quota 이벤트 는 type, meter, reset_at만 포함합니다. 기존 예시의 사용량 숫자는 서버 키에만 전달됩니다.
  • end가 반복하는 카드·레이어 이벤트는 다섯 가지 뿐입니다. weather_card, satellite_card, constellation_layer, weather_layer, vehicles_layer이며 전부가 아닙니다.

SSE 전송 규약을 참조하세요.

엔드포인트

  • POST /design/analyze와 POST /design/apply-direct의 요청 본문 설명에 오류가 있었습니다. 예전 analyze 본문은 422를 반환했습니다. 두 설명을 수정했고 카탈로그 응답도 감싸는 키와 함께 표시합니다.
  • POST /chat/control/route는 각 장소의 lat, lng를 coordinates 아래가 아닌 최상위에 받습니다.
  • POST /chat/control/stream에 전송된 system 메시지는 무시됩니다. 기존 문서에 없던 내용입니다.

엔드포인트를 참조하세요.

게시된 지도 및 공유 링크

  • 게시 지도는 현재 저장된 상태를 보여줍니다. 이전에는 임베드가 '마지막 게시 버전'을 보여주고 Re-publish로 업데이트한다고 했지만 사실과 다릅니다. Studio에서 저장한 변경은 데이터 세트 추가를 포함해 다시 게시하지 않아도 다음 임베드 로드 시 공개됩니다. Re-publish는 새 게시 버전을 기록하지만 ID, 링크, 임베드 코드는 유지합니다. 비공개로 수정하려면 먼저 게시를 취소하고 작업 후 다시 게시하세요. 지도 임베드를 참고하세요.
  • Studio에서 공유 링크를 삭제하거나 일시 중지할 수 없습니다. Share 대화상자를 열면 지도가 게시되고 매번 새 공유 링크가 생성됩니다. 링크는 지도 디자인의 스냅샷으로, 지도가 게시 취소된 뒤에도 지도 삭제 또는 Kaleidr의 요청에 따른 제거 시까지 계속 작동합니다. 삭제·일시 중지할 수 있다는 예전 설명은 실제 제공 기능이 아닙니다. 공유 링크를 참고하세요.

SDK 및 임베드

  • Chat은 지도를 이동합니다. 카메라를 제어하지 않는다는 이전 설명은 틀렸습니다. 실제로 답변의 장소로 지도를 이동·맞춤하고 전용 핀과 경로를 그립니다. Chat 마운트 핸들의 setCamera만 지원되지 않습니다.
  • Editor의 범위. 내장 Editor는 페이지 내부에서 작동하고 작업을 페이지 메모리에 보관합니다. 저장·내보내기·게시를 하지 않으며 디자인 API도 호출하지 않습니다. 임베드에서 게시할 수 있다는 설명은 잘못됐습니다.
  • Content Security Policy 호스트. Editor는 https://tile.kaleidr.com에서 기본 지도를 불러오지만 이전 정책 문서에는 빠져 있었습니다. 기본적으로 외부 지도 호스트에 연결하는 임베드는 없습니다. Chat은 인용한 웹사이트의 아이콘을 Google favicon 서비스에서 로드하며, 이제 정책 문서와 기능 및 제한에 포함됩니다.
  • Leaflet을 Chat 지원 지도로 다시 문서화했습니다. Mapbox GL JS, MapLibre GL JS, Google Maps JavaScript API와 함께 사용할 수 있습니다.
  • Tile 프레임 URL에는 인증 정보가 없습니다. 스타일 ID와 카메라만 포함하고 게시 가능 키나 세션 토큰은 없습니다. Tile 세션 교환은 키를 확인하고 지도 로드를 계산하며 조직의 기본 지도를 반환합니다. 프레임 안의 지도는 이 인증 정보로 요청하지 않습니다. Tile 참고를 참고하세요.
  • Kaleidr.enable(false)는 호출 이후의 마운트만 보류합니다. 로더가 실행될 때 브라우저가 이미 읽은 <kaleidr-map> 요소는 호출 전에 바로 마운트됩니다. 로더보다 앞서 window.__KALEIDR_EMBED_ENABLED__ = false를 설정하세요.
  • 옵션 객체 없이 Kaleidr.mount를 호출하면 TypeError가 발생합니다. 그 외의 마운트 실패는 [kaleidr:<product>]가 들어 있는 콘솔 오류(Error: [kaleidr:… 형식)를 한 번 기록하며 예외를 발생시키지 않습니다.
  • 내장 Editor 도구 모음 에는 Text, Image, Marker, Popup, Background, Layer, Design, Legend가 있습니다. Design이 없다는 이전 설명은 틀렸으며 실제로 빠진 것은 Studio 디자인 카탈로그, Data 탭, AI 패널, 3D 모델 라이브러리입니다.
  • kaleidr-plain은 줌 15부터 3D 건물 을 표시합니다. 이전에는 없다고 했습니다.
  • 스타일도 조직 기본값도 없는 Tile 은 kaleidr-embed:error와 함께 code: 'no_id', id: null을 전송합니다.
  • Viewer의 shareId 에는 게시된 지도 ID 또는 공유 링크의 16자 ID를 쓸 수 있습니다. 게시 지도 Chat은 지도 ID만 받습니다.

새 페이지​

2026-10​

  • 주소 결과에 자세한 정보가 추가됐습니다. GET /retrieval/geocode/forward는 도로명 주소에 데이터 갱신 후에도 같은 문을 가리키는 Kaleidr ID인 id를 포함합니다. 추정 주소에는 method, matched_numbers에 더해 within_m, score도 포함됩니다. method는 "range"일 수 있으며 미국의 주택 번호를 해당 블록을 따라 배치했다는 뜻입니다. 모두 기존 기능에 추가된 값입니다. 엔드포인트를 참고하세요.
  • Free 요금제의 API 키. Free 조직의 게시 가능 키는 기본 지도뿐 아니라 AI Chat, 게시 지도, Editor에도 사용할 수 있습니다(범위 ai, maps, design, 모든 제품). Free AI 크레딧을 소비합니다. 서버 키는 Pro 또는 Enterprise가 필요합니다. (vendor 범위는 2026-10-13부터 Enterprise 전용입니다.) 조직의 활성 키 한도는 Free 2, Pro 10, Enterprise 25입니다(초과 시 409 key_limit_reached, 회전은 세지 않으며 기존 초과 키는 보관).

2026-09​

  • 주소 검색에서 도로명 주소 지원. GET /retrieval/geocode/forward가 입력한 도로명 주소(type: "address")도 반환합니다. attribution.sources에는 사용한 각 주소 데이터 세트와 출처, 라이선스 제한이 포함되며 G-NAF 결과를 우편 주소 목록 작성에 사용할 수 없습니다. 데이터에 없는 집 번호는 같은 거리의 가까운 번호에서 추정하여 approximate: true, method, matched_numbers로 표시합니다. 기존 장소 검색은 그대로입니다.
  • 대중교통 경로. POST /chat/control/route는 profile: "transit"를 허용하고 환승 없는 여정을 action.payload.transit에 반환합니다. 직행편이 없으면 { "error": "…" }를 반환합니다. 요청 본문과 다른 profile의 동작은 변경되지 않았습니다. 새 GET /retrieval/geocode/forward(범위 ai, 유료)는 출발지·도착지 검색창에 사용됩니다. Chat 경로 안내에는 입력 가능한 From/To 필드와 Transit 모드가 추가됐습니다.
  • 키 권한은 현재 요금제를 따릅니다. 세션 교환 및 런타임 요청 때마다 조직의 현재 요금제에 맞춰 키를 확인하므로 키를 수정·회전하지 않아도 요금제 변경이 적용됩니다. tier_capability_not_allowed는 키가 권한이 있지만 요금제에서 제외된 경우이고, insufficient_scope는 키에 처음부터 권한이 없던 경우입니다.
  • 요금제 변경은 발급된 세션에 영향을 줍니다. 다운그레이드하면 이전 세션이 만료 시각 대신 몇 분 안에 종료됩니다. 업그레이드는 다음 세션 교환부터 적용됩니다.
  • Free 제품 변경이 검증됩니다. Free 키의 allowed_products를 빈 목록이나 지원하지 않는 제품으로 바꾸면 403 tier_capability_not_allowed입니다.
  • 스트림 이벤트 grounding이 제거됐습니다. 이를 듣던 클라이언트는 더 이상 받지 못합니다.

2026-08​

  • 기본 지도 접근에는 키가 필요합니다. tile.kaleidr.com을 제3자가 직접 사용하는 것은 제한되지만 <kaleidr-map> 임베드와 Kaleidr 호스팅 지도는 영향을 받지 않습니다. Tile 세션은 조직의 지도 로드에 포함됩니다(할당량).
  • 세션 교환 및 갱신. 게시 가능 키는 출처에 묶인 단기 세션(kld_sess_…, 15분)으로 교환되며 SDK가 갱신합니다.
  • Chat은 Kaleidr 지도 요소를 제어할 수 있습니다. Chat을 마운트할 때 map-target을 같은 페이지의 Viewer 또는 Tile 요소로 지정할 수 있습니다.
  • 조직 기본 지도. POST /sdk/sessions는 basemap_style_id로 조직 기본 지도를 반환하며 스타일을 지정하지 않은 임베드가 사용합니다.
  • 브라우저에서는 서버 키가 거부됩니다. SDK는 마운트 시 kld_sk_…를 거부합니다.
  • 기본 주소 옵션 분리. viewerBase, tileBase가 로더의 base 옵션에서 분리됐습니다.
  • 경로 색상. route 스트림 이벤트에는 color, label, alternatives, comparison이 포함됩니다.

v1​

  • kaleidr.js 로더 및 <kaleidr-map> 요소: 로더 하나로 네 제품(Chat, Viewer, Editor, Tile)을 제공합니다.
  • ai, maps, design, vendor 범위가 있는 브라우저 게시 가능 키(kld_pk_)와 서버 키(kld_sk_). 게시 가능 키는 출처에 연결된 짧은 세션으로 교환됩니다. 기존 kld_live_ 키도 계속 작동합니다.
  • /inference-api/b2b/v1/chat/*(스트리밍)와 /design/* 엔드포인트 계열.