跳到主要内容

更新日志

本页记录嵌入式 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（或用 prompt-param 从页面 URL 读取）和 iframe 的 q 参数会在地图打开时向地图的 Kaleidr AI 提出问题，handle.send() 则从代码中提问。此为新增功能，版本不变。
  • 根据地图自身地点回答现已开启。 已发布地图或分享链接上的 Ask Kaleidr 面板会优先根据地图显示的命名地点回答。参阅根据地图自身地点回答问题。
  • 模板商店为您生成代码。 template.kaleidr.com 会为您选择的地图生成这两段代码片段。可下载的网站模板已停用。

2026-10-18：分享链接的 Kaleidr AI 需要其地图处于发布状态​

  • 地图取消发布后，分享链接的 Kaleidr AI 随之停止。 它也只在地图当前允许域名所包含的网页上可用，而不再依据链接快照中的域名。取消发布地图或删除网页域名后，与已发布地图一样，会在五分钟内停止；再次发布即可恢复。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 不会关闭已分发出去的分享链接上的 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 及指向替代接口的 Link。参见 从弃用接口迁移。
  • 现在会返回 tenants。 /spot 会将楼宇中的商家作为具有 poi: 引用的 tenant 实体返回，遵循 CDLA-Permissive-2.0，而不再隐藏这些数据。该项查询仍免费。
  • 每次摘要均计费。 地点摘要或概述按每次请求实际使用的 token 计费；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 组织的所有者或管理员可以上传并发布。只有在组织仍使用 Enterprise 时，Kaleidr Studio 助手才会向该组织已登录成员提供基于这些数据的回答。Free 和 Pro 无法上传。地点数量、文档数量和文件大小限制按组织在协议中约定，且不得超过平台上限。超限上传会返回 422，并在原因中注明限额和套餐。以组织在 kaleidr.com/billing 购买及更改的 Kaleidr 套餐为准。通过 API 密钥或 SDK 读取此类数据还需要 Enterprise 专属的 vendor 权限范围。参见 各套餐可用功能。
  • 地图数据集的限制取决于套餐。 已登录用户可以在所有套餐中通过 Studio 数据面板向地图添加文件，但受不同限额约束：Free 每个数据集最多 50,000 行、每个文件 32 MiB、组织所有数据集合计 250,000 行；Pro 分别为 100,000 行、64 MiB 和 5,000,000 行。Enterprise 的单数据集和单文件上限与 Pro 相同，组织总量在协议中约定。超出套餐限额时，仅拒绝新的上传并返回 HTTP 402 quota_exceeded，已存储的数据不受影响。另有四项适用于所有套餐（包括 Enterprise）的硬上限，超出时返回 HTTP 400 VALIDATION_ERROR，而不是 402：文件超过 64 MiB、数据集超过 100,000 行、地理文件超过 50,000 个要素、图像叠加层超过 16 MiB（指 Studio 从 GeoTIFF 生成的图像，而非 GeoTIFF 原始文件）。粘贴至 Studio 上传器的 JSON 对所有用户都存储于地图内部，不计入这些限额。参见 地图上的数据集 和 错误。
  • 被拒绝的数据集上传不会向地图添加任何内容。 Studio 会在上传控件附近显示服务器的任何拒绝原因，且不添加文件：套餐限额（402，附服务器提示和 Upgrade Plan 链接）、未登录会话、权限不足、文件过大、上传次数过多或其他拒绝，包括超过通用硬上限时的 400。只有服务器无响应、超时或故障时，系统才可能改为将行存入地图并显示警告，而且表格必须仍在套餐限额内；否则什么都不添加。参见 上传未成功时。
  • 在数据面板删除数据集将永久删除。 点击已存储数据集的垃圾桶后需要确认，随后删除该数据集、从地图移除其图层，并释放组织总行数配额。已发布地图和分享链接都将停止提供该数据集。上传同名文件会在新数据成功存储后替换旧数据；若新文件无法读取，地图会恢复旧数据并给出提示。“撤销”可能恢复地图对已删除数据集的引用，但该图层将无法绘制。参见 删除或替换数据集。
  • Studio 的限制与组织 Kaleidr 套餐一致。 组织可保留的地图数量及上述数据集限额均由在 kaleidr.com/billing 购买或调整的套餐决定。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 密钥不能拥有此权限。低于 Enterprise 的套餐请求创建带 vendor 的密钥会返回 403 tier_capability_not_allowed；以前 Free 会静默删除该权限，Pro 则允许创建。低套餐中轮换原本带 vendor 的密钥时，新密钥不再包含它。组织从 Enterprise 降级后，原有密钥会在无报错的情况下失去数据访问能力，浏览器中已有会话也将结束。Pro 仍支持服务器密钥及更多有效密钥。参见 认证与权限范围。
  • Chat 支持语言、标题和占位提示。 新增挂载选项 lang、title、placeholder；元素属性为 lang、chat-title、placeholder。未设置 lang 时，面板使用页面有效的 <html lang> 属性，否则使用英语。参见 Chat 参考。
  • <kaleidr-map> 默认是块级元素。 除非 CSS 覆盖，否则元素为 display:block，因此设置的 height 可以生效。此前若未另行设置 display:block，高度无效。示例代码中仍保留 display:block，以兼容 Safari 16.4 之前版本。参见 尺寸设置。
  • 挂载后立即调用的控制句柄方法会被保留。 对 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 严格模式下的情况。
  • 被拒绝的请求不会占用积分。 在处理前由于频率、并发、验证失败或请求体过大而被拒绝的请求，不再保留任何 AI 积分或并发名额。参见 配额与频率限制。
  • Viewer 和 Tile 优先采用页面传入的相机参数。 加载时传入的相机设置（center、zoom、pitch、bearing 或 iframe URL 中的 camera），或通过 setCamera 设置的相机，会覆盖作者保存的视图，包括依据访客屏幕宽度与内容自动调整的视图，并终止尺寸变化时的自动重新取景。页面未传的字段仍沿用作者设置；只传 zoom 而不传 center 会被忽略。参见 相机设置。
  • Viewer 或 Tile 元素上的 Chat 会保留标记。 与其他地图一样，多个回答的标记会持续累积；再次提到同一地点但坐标改变时，更新已有标记的位置，而不是新增标记。关闭或销毁聊天会移除其标记、路线和所有其他绘制内容。参见 能力与限制。
  • Chat 的 title 是面板标题。 传入的标题会在每段对话开始后显示于聊天窗口标题栏；过去它会被从对话生成的标题替换。最小化的聊天窗口显示所属对话的标题。参见 标题与占位提示。
  • Editor 使用可发布密钥标识底图请求。 通过 kaleidr.js 挂载的 Editor 在向 https://tile.kaleidr.com 请求样式、精灵图和字体时，会附带页面的可发布密钥。会话令牌绝不会放在 URL 中，无需新增选项。参见 页面中运行的内容。

API 限制和拒绝​

  • 聊天流请求有限额和专用错误码。 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。
  • 未完整结束的聊天流 至少按其发送的会话内容计费。
  • 会话令牌可见信息更少。 对会话令牌，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 积分配额不足时请求返回 429，正文包含 "error": "quota_exceeded"。旧文档展示的 b2b.tokens_exceeded 从未由 API 返回，且响应示例缺少 detail、product 和 period。
  • map_load_hard_stop 错误码不存在。参见下文“套餐”。
  • 从密钥允许列表以外的来源交换会话时返回 403 origin_not_allowed。旧文档误写为 session_origin_mismatch；后者用于会话令牌从签发来源以外的来源使用。
  • vendor_scope_requires_acknowledgement 是 422 而非 403，仅适用于可发布密钥。
  • sessions_disabled 是 404，sessions_not_configured 是 503；以前两者都标成 403。
  • 401 响应包含 {"detail": "Invalid or missing API key"}；旧文档称其无响应体。
  • map_load_quota_exceeded 的实际结构为 {"detail": "map_load_quota_exceeded"}，过去展示的扁平对象不存在。
  • 密钥服务故障返回 401，不是 503。
  • 向 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 起可用”。实际上，商家数据的上传及通过 API/SDK 的 vendor 权限读取均为 Enterprise 专属。Free 和 Pro 的另一项功能是将数据集添加到 Kaleidr Studio 地图。参见上方“产品变更”。
  • 所有套餐的地图加载在达到限额后都会停止。 旧文档称付费套餐可继续使用五倍额度，这一行为并不存在。购买地图加载包可提高限额。
  • AI 积分由组织共享一个资金池， 组织 API 密钥和团队使用 Kaleidr 自有应用均从中扣除。旧文档曾描述独立的每月 API token 预算。
  • 配额周期取决于账单周期，不一定是自然月。
  • 频率限制按密钥计算，并发限制按组织计算。旧文档误称不同密钥共享频率限制。
  • 可发布密钥的允许来源列表是可选的。旧文档曾要求正式密钥至少配置一个来源；空列表表示允许任何来源。
  • 密钥创建后不能编辑权限范围。 此前关于增加或移除权限的说明有误；请创建新密钥并撤销旧密钥。
  • 服务器密钥和旧版密钥可直接用于运行时 API 调用；旧文档误称所有调用都需会话令牌。
  • Free 套餐中的密钥轮换。 轮换可发布密钥后，新密钥具有完整的 Free 权限（ai、maps、design 和全部四种产品），不受旧密钥配置影响。Free 轮换服务器或旧版密钥返回 403 free_plan_publishable_only。
  • monthly_cap_tokens： 取 1 或更大值表示限额；0 或 null 表示不设限。
  • 创建密钥时的 org_id 应放在 JSON 请求体中；其他密钥接口才会读取查询参数 org_id。
  • Visitor AI Chat 会计入每个请求。 一次提问需要一次回答请求，且回答中的每张结果卡还会触发一次照片请求。打开地点卡、继续提问、在路线规划中查找地址和请求路线，都属于额外请求并计入访客限额。参见 已发布地图上的 Chat。

参见配额与速率限制和身份验证与权限范围。

流式传输

  • 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 的请求体说明曾有错误，按原示例发送设计分析会返回 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。此前声称能从嵌入式 Editor 发布的描述有误。
  • 内容安全策略的域名。 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 对街道地址新增 id（Kaleidr 为门牌分配、跨数据更新保持不变的标识符）；估算地址还在 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 路线界面新增可输入的起终点字段和公交模式。
  • 密钥权限取决于当前套餐。 会话交换和所有运行时调用都会按组织当时的套餐检查密钥，因此更改套餐无需编辑或轮换密钥即可生效。tier_capability_not_allowed 表示密钥有权限但当前套餐不包含；insufficient_scope 表示密钥从未拥有该权限。
  • 套餐更改会影响已签发会话。 降级会在数分钟内终止此前签发的会话，而不是等到过期。升级在下次会话交换时生效。
  • Free 套餐的产品修改会被检查。 将 Free 密钥的 allowed_products 改为空列表或套餐不支持的产品，会返回 403 tier_capability_not_allowed。
  • 移除了 grounding 流事件。 监听该事件的客户端将不再收到它。

2026-08​

  • 底图访问需要密钥。 限制第三方直接使用 tile.kaleidr.com；<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）。
  • 浏览器可发布密钥（kld_pk_）及服务器密钥（kld_sk_），支持 ai、maps、design 和 vendor 权限；可发布密钥需要交换为短期、绑定来源的会话。旧版 kld_live_ 密钥继续有效。
  • /inference-api/b2b/v1/chat/*（流式）和 /design/* 接口系列。