端点

Kaleidr 平台 API 的每个公开端点都有单独的说明章节。

• 基础 URL： https://api.kaleidr.com/inference-api/b2b/v1
• 凭证： Authorization: Bearer … 或 X-Api-Key: …。后端使用服务器密钥（kld_sk_live_…），浏览器使用会话令牌（kld_sess_live_…）。可公开密钥只能用于会话交换。参见身份验证与权限范围。
• 请求体： JSON、UTF-8。每个 POST 请求都需发送 Content-Type: application/json。请求体大小不得超过 2 MiB，/design/* 端点为 5 MiB；超出限制将返回 413 request_too_large。
• 错误： 返回 4xx 或 5xx 状态及 JSON 响应体，详见错误。有一个端点通过 200 返回失败，参见路线规划。

以下示例使用保存在环境变量中的服务器密钥：

export KALEIDR_KEY="kld_sk_live_…"

摘要

端点	用途	权限范围	计费
POST /sdk/sessions	将可公开密钥交换为会话	产品所需权限范围	tile 消耗一次地图加载；其他情况免费
POST /sdk/share-sessions	将已发布地图 ID 交换为聊天会话	无	免费
POST /chat/control/stream	提问并流式返回回答、地点、操作和路线	ai	按使用的 Token 消耗 AI 积分
POST /chat/control/route	为已知坐标之间规划路线	ai	免费
GET /retrieval/geocode/forward	将输入文本转换为地点与地址	ai	固定额度 AI 积分
POST /spot	查询某点的地点、地址、所属区域及可选内容	ai	固定额度 AI 积分
POST /spot/overview/stream	流式生成 /spot 所返回对象的简短介绍	ai	按使用的 Token 消耗 AI 积分
GET /retrieval/poi/enrich	已弃用，请使用 /spot。获取地点详情和照片	ai	固定额度 AI 积分
POST /chat/summary/stream	已弃用，请使用 /spot/overview/stream。流式返回地点或建筑简介	ai	按使用的 Token 消耗 AI 积分
POST /chat/button/stream	流式回答关于某个地点的单独问题	ai	按使用的 Token 消耗 AI 积分
POST /design/analyze	根据数据表推荐地图设计	design	固定额度 AI 积分
POST /design/apply-direct	根据数据表和选定样式创建地图图层	design	免费
GET /design/styles, /design/samples, /design/themes	设计资源目录	design	免费

有关计费、预留额度和限制的工作方式，请参阅配额与速率限制。

所有运行时端点都可能返回所有运行时端点共有的错误中列出的错误。以下各节仅列出端点特有的错误。

---

POST /sdk/sessions

将可公开密钥交换为短期有效的会话令牌，令牌绑定发起请求的来源和指定产品。SDK 会为每次使用密钥的挂载操作自动执行此流程；仅在自行开发浏览器客户端时才需要直接调用。

**身份验证：**可公开密钥。要求：Origin 请求头（浏览器会自动添加）。**费用：**当 product 为 tile 时计一次地图加载；其他情况免费。

字段	类型	必填	说明
product	字符串	是	chat、editor、viewer 或 tile。

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "X-Api-Key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"product":"chat"}'

{
  "session_token": "kld_sess_live_eyJhbGciOi…",
  "expires_in": 900,
  "product": "chat",
  "basemap_style_id": null
}

basemap_style_id 是组织的默认底图；未设置时为 null。

状态码	错误代码	触发条件
401	Invalid or missing API key	密钥未知、已撤销或已过期。
403	publishable_key_required	提供的是服务器密钥或旧版密钥。
403	origin_required	缺少 Origin 请求头。
403	origin_not_allowed	请求来源不在密钥允许的来源列表中。
403	product_not_allowed	密钥允许的产品不包含 product。
403	tier_capability_not_allowed	当前套餐不包含产品或相应权限范围。
403	insufficient_scope	创建密钥时未赋予所需权限范围。
422	参数校验	未提供 product，或不是四个允许值之一。
429	rate_limited	该密钥的会话交换请求过多。Retry-After: 5。
429	map_load_quota_exceeded	仅适用于 tile：地图加载配额已耗尽。
404	sessions_disabled	平台已禁用会话服务。请联系支持团队。
503	sessions_not_configured	平台故障。请重试；若问题持续，请联系支持团队。

有效期、续期规则和检查顺序见身份验证与权限范围：会话交换。

POST /sdk/share-sessions

将已发布地图的 ID 交换为聊天会话，让访问者无需在网页中提供密钥即可聊天。地图在 Studio 中的 Kaleidr AI 磁贴必须开启所请求的功能。

**身份验证：**无。要求：Origin 请求头。**费用：**无；该会话的聊天调用费用由地图所有者的组织承担。

字段	类型	必填	说明
share_id	字符串	是	长度为 1 至 128 个字符，只能包含字母、数字、_ 和 -。
feature	字符串	否	control_tower（默认值），即地图的 Ask Kaleidr 面板；或 popups，即弹出窗口中的 AI 聊天。每项仅在其开关开启时授予。

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"share_id":"your-map-id","feature":"control_tower"}'

{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }

状态码	错误代码	触发条件
403	origin_required	缺少 Origin 请求头。
404	not_found	未找到具有该 ID 的已发布地图或分享链接，或分享链接的地图已取消发布。
403	chat_disabled	地图的 Kaleidr AI 未开启所请求的功能。
403	origin_not_allowed	网页不在地图允许的域名列表中。
403	owner_has_no_organization	地图所有者没有可用于计费的组织。
403	tier_capability_not_allowed	所有者套餐不包含聊天功能。
422	参数校验	share_id 缺失或包含不允许的字符，或 feature 不是上述任一值。
429	rate_limited	此地图或该地址发起的会话交换过多。Retry-After: 5。
404	sessions_disabled	平台已禁用会话服务。
503	share_grant_unavailable、sessions_not_configured	平台故障，请重试。

参见已发布地图上的 Kaleidr AI。

---

POST /chat/control/stream

接收问题并以流式方式返回回答，包括逐步生成的文字、所提及地点及其坐标、地图操作与路线。这是 Kaleidr Chat 背后的端点。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，按答案使用的令牌数计费。 响应：text/event-stream，详见 SSE 数据流协议。

字段	类型	必填	默认值	说明
messages	{ role, content } 数组	否	[]	截至当前的对话，按时间从早到晚排列，以用户的新消息结尾。role 为 user 或 assistant。其他角色（包括 system）以及 content 为空的消息均被忽略。 回答最后一条 user 消息。大小限制见下文。
session_id	字符串	否	自动生成	对话标识符，1 至 128 个字符，可使用字母、数字、_、.、: 和 -。请提供稳定 ID，并在后续轮次重复使用。省略时服务器会为本次请求生成 ID，并通过 phase 和 start 事件返回。
location	对象 { lat, lng }	否	无	用户正在查看的位置，即地图中心点，用于理解“这附近”等提问。
map_zoom	数字	否	无	地图缩放级别。
lang	字符串	否	"en"	回答语言，使用 BCP 47 标记，例如 fr 或 pt-BR，最多 35 个字符。
layout	字符串	否	无	对话所在的 viewer 布局：嵌入的 viewer 显示其导览布局时为 "guide"；否则请省略。最多 16 个字符。
app_snapshot	对象	否	无	接受该字段，但不需要；请省略。
auto_actions	布尔值	否	无	接受该字段，但不需要；请省略。

未知字段会被接受但忽略。请求体中没有提供系统指令、角色设定、工具或自定义上下文的字段；请求仅包含对话、位置和语言。

服务器不会替您存储对话记录。每次调用时，使用相同的 session_id，并在 messages 中发送之前的对话轮次。

session_id 仅用于你的组织。对话的短期上下文按组织隔离，所以其他组织即使使用相同的 ID，也无法查看或修改你的对话。在自己的组织内部，请为每位最终用户的每段对话分配独立 ID。

请求限制

超出任一限制的请求会在生成答案之前被以 422 拒绝，且不计费。响应正文为 {"detail": "<code>"}。

限制	数值	错误代码
messages 中的消息数量	400	too_many_messages
单条消息 content 的长度	64,000 个字符	message_too_long
所有 content 的总长度	200,000 个字符	conversation_too_long
session_id	1 至 128 个字符：字母、数字、_、.、:、-	invalid_session_id
lang	35 个字符	lang_too_long
layout	16 个字符	invalid_layout

所有消息都计入这些限制，包括会被忽略的消息。长对话通常会先触及总长度上限，而不是消息数量上限。仅发送最新且必要的轮次，并移除较早内容：参见读取数据流。

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "session_id": "trip-42",
    "messages": [{"role": "user", "content": "Where is the Louvre, and what is next to it?"}],
    "location": {"lat": 48.8566, "lng": 2.3522},
    "map_zoom": 12,
    "lang": "en"
  }'

-N 会关闭 curl 的输出缓冲，使数据帧在到达时立即打印。以下是包含示例值的简化响应：

event: phase
data: {"type": "phase", "phase": "thinking", "session_id": "trip-42"}

: keep-alive

event: start
data: {"type": "start", "session_id": "trip-42", "purpose": "control"}

data: {"text": "The [[Louvre Museum]] is on the right bank of the Seine"}

event: place
data: {"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}

data: {"text": ", with the [[Tuileries Garden]] directly to its west."}

event: place
data: {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}

event: early_actions
data: {"type": "early_actions", "actions": [{"type": "map.fitBounds", "payload": {"coordinates": [[2.3376, 48.8606], [2.3275, 48.8635]], "padding": 50, "maxZoom": 15, "duration": 1000}}], "places_count": 2, "is_partial": true}

event: end
data: {"type": "end", "full_text": "The [[Louvre Museum]] is on the right bank of the Seine, with the [[Tuileries Garden]] directly to its west.", "places": [{"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}, {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}], "actions": [], "question_type": "…", "response_time": 6.4, "total_tokens": 3120}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

状态码	错误代码	触发条件
413	request_too_large	请求体超过 2 MiB。
422	参数校验	请求体不是有效 JSON，或字段类型错误。
422	too_many_messages、message_too_long、conversation_too_long、invalid_session_id、lang_too_long、invalid_layout	请求超出大小限制。
429	quota_exceeded	AI 积分池或此密钥的月度上限不足以支付请求。

示例中的 quota 事件是服务器密钥收到的版本。使用会话令牌读取数据流时，该事件包含的信息较少，详见quota 事件。

流开始后，失败会作为 error 事件到达，而不是以 HTTP 状态码表示。有关客户端实现，请参阅读取数据流。

POST /chat/control/route

使用已知坐标规划两点之间的路线。不提问，也不生成文本。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**无。但仍需有足够的 AI 积分余额才能接受调用。

字段	类型	必填	默认值	说明
places	对象数组	是，至少两个	[]	每个对象为 { lat, lng, name? }，并且数字类型的 lat 和 lng 必须直接位于对象顶层。也可以用 label 代替 name。lat 和 lng 坐标无效或不是数字的条目会被静默跳过。
profile	字符串	否	"driving"	driving、walking、cycling 或 transit。其他值都按 driving 规划。
raw_query	字符串	否	"Show directions"	用户输入的原始文字（如果有）。

第一个地点为起点，最后一个地点为终点。

地点对象的数据结构与聊天数据流不同

聊天流的 place 事件将坐标嵌套在 { "coordinates": { "lat": …, "lng": … } } 中，但此端点要求 lat 和 lng 直接位于对象顶层。原样传入聊天流的地点会得到 error 响应，因为其中没有可用的顶层坐标。

curl -s https://api.kaleidr.com/inference-api/b2b/v1/chat/control/route \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "places": [
      {"name": "Louvre Museum", "lat": 48.8606, "lng": 2.3376},
      {"name": "Tuileries Garden", "lat": 48.8635, "lng": 2.3275}
    ],
    "profile": "walking"
  }'

成功的响应为包含 action 的 200（数值仅作示例）：

{
  "action": {
    "type": "map.showRoute",
    "payload": {
      "id": "control-directions",
      "label": "Directions",
      "profile": "walking",
      "coordinates": [[2.3376, 48.8606], [2.3352, 48.8619], [2.3275, 48.8635]],
      "distance_m": 870,
      "duration_s": 640,
      "turn_by_turn": [{ "text": "Walk west on Rue de Rivoli." }],
      "attribution": {
        "text": "© OpenStreetMap contributors",
        "url": "https://www.openstreetmap.org/copyright",
        "license": "https://opendatacommons.org/licenses/odbl/"
      }
    }
  },
  "route": { "…": "the full planning result the action was built from" }
}

绘制 action.payload.coordinates，它是一组 [lng, lat] 坐标对。distance_m 单位为米，duration_s 单位为秒。显示路线时必须展示 attribution.text，并链接至 attribution.url。

当 profile: "transit" 时，payload.transit 表示一次无需换乘的行程：步行、乘坐一趟交通工具、再步行。此时顶层结果中没有 attribution；运营商来源信息位于 payload.transit.attribution，应随行程一起显示。

此端点使用 HTTP 200 报告失败

**无法规划路线并不是 4xx 错误。**响应为 200，包含 error 字符串而不包含 action：

{ "error": "Route planning failed." }

当规划器无法连接这些地点或因其他原因规划失败时，就会出现这种响应。如果有效坐标的地点少于两个，返回文字为 At least two resolved places are required to build a route.。这段文字可直接显示给用户，因此应判断是否存在 error 字段，不要依赖错误文案。若没有直达公交行程，也会以相同方式返回失败，并额外提供 reason、covered 和 available 三个字段。

应根据响应正文而不是状态码进行分支判断：

const res = await fetch(`${API}/chat/control/route`, { method: 'POST', headers, body });
if (!res.ok) throw new Error(`route request refused: ${res.status}`); // 401, 403, 422, 429
const data = await res.json();
if (data.error) {
  showMessage(data.error); // a 200 that is a failure
} else {
  drawLine(data.action.payload.coordinates);
}

身份验证、权限范围、验证、配额及速率限制失败，仍以普通的 401、403、422 和 429 响应返回。

GET /retrieval/geocode/forward

将输入的文本转换为匹配的地点和街道地址。适用于搜索框或出发地/目的地输入框。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，按次收取固定费用。即使 results 为空也会计费。

参数	类型	必填	默认值	说明
q	字符串	是		1 至 200 个字符：地点名称、带门牌号的街道地址，或输入的 lat,lng。
near_lat	数字	否		−90 至 90。附近的匹配项排名更高；必须和 near_lng 一起使用。
near_lng	数字	否		−180 至 180。必须和 near_lat 一起使用。
limit	整数	否	5	1 至 20。
mode	字符串	否		出行方式（driving、walking、cycling、transit）。短距离行程会提高附近结果的排名。

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/geocode/forward \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "q=20 W 34th St, New York" \
  --data-urlencode "limit=3"

{
  "query": "20 W 34th St, New York",
  "results": [
    {
      "lat": 40.7484,
      "lng": -73.9857,
      "display_name": "20 W 34th St, New York, NY 10001",
      "type": "address",
      "source": "…",
      "id": "…",
      "confidence": "exact",
      "attribution": {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    }
  ],
  "attribution": {
    "text": "Overture Maps Foundation, overturemaps.org",
    "licenses": [
      "https://cdla.dev/permissive-2-0/",
      "https://www.apache.org/licenses/LICENSE-2.0",
      "https://opensource.foursquare.com/places-notice-txt/",
      "https://docs.overturemaps.org/attribution/"
    ],
    "sources": [
      {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    ]
  }
}

所有结果均包含 lat、lng、display_name、type 和 source。其他字段仅在适用时出现：

结果字段	含义
id	街道地址对应的 Kaleidr 门牌标识符。数据更新后仍保持不变，可保存并比较。
confidence	输入文字与结果的匹配方式（见下表）。输入 lat,lng 时不提供。
approximate、method、matched_numbers、within_m、score	仅适用于下述估算地址。
attribution	此结果来源数据集的条款：dataset、license，以及适用时的 license_url、attribution（需要显示的署名）和 use_restriction。

confidence	结果含义
exact	输入的门牌号、街道和地点均完全一致。
fuzzy	同样匹配，但输入的街道名称存在拼写错误。
name_exact	地点名称与输入文字完全一致。
locality	输入文字指定的城镇、地区或街区。
interpolated、nearest	数据集中缺失门牌号时生成的估算位置。
partial	街道完整名称以输入内容开头。
name_partial	地点名称与输入内容部分相同。
ambiguous	未指定所属地点，也没有附近参考点的地址：存在多个可能结果。

估算地址。 如果数据中不存在输入的门牌号，系统会将其放在对应街道上：同侧两个已知门牌号之间、最近的已知门牌号处，或该号码所属街区范围内。估算结果带有 approximate: true，以及以下字段：

字段	含义
method	"interpolated"（位于两个已知门牌号之间）、"nearest"（靠近一个已知号码）或 "range"（沿街区放置）。
matched_numbers	用于估算位置的已知门牌号。
within_m	已知门牌号间距离或街区长度（米）：当沿街编号有序时，估算误差的上限。"nearest" 情况下省略。
score	0 到 1 的置信度；低分时应将结果视为街道级位置，而非精确门牌位置。

精确匹配结果不会包含这些字段。

来源署名。 将顶层 attribution 随结果一起传递。其 text 是需要展示的署名文字，licenses 列出必须随数据提供的许可条款。如果结果包含街道地址，attribution.sources 会列出使用的地址数据集。使用这些结果时必须遵守其 use_restriction：

数据集	需要显示的署名	使用限制
au/countrywide (G-NAF)	G-NAF © Geoscape Australia，经澳大利亚联邦授权，依据 Open Geo-coded National Address File (G-NAF) End User Licence Agreement 使用。	不得用于生成邮寄地址或邮寄地址汇编，除非每个地址均经 G-NAF 以外的来源验证可接收邮件；使用行为必须符合 Australian Privacy Principles。
ca/countrywide (Statistics Canada)	改编自 Statistics Canada, National Address Register, 2025-07-29。此举并不代表加拿大统计局认可本产品。	不得用于识别任何个人、企业或组织，也不得暗示其认可。
us/ny/city_of_new_york	地址数据来源：NYC Department of City Planning。	无。
us/ma/statewide (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	无（公共领域）。

无匹配和内部失败的响应相同。 查询不到结果时，返回 200 和 "results": []。内部查询失败时也可能返回同样内容，但此时不计费。因此应将空数组视为“没有可展示内容”，而不是错误。

状态码	错误代码	触发条件
422	参数校验	q 缺失、为空或超过 200 个字符；limit 或坐标超出范围。
429	quota_exceeded	AI 积分池不足以支付请求。

POST /spot

说明指定坐标点有什么：用户点击的地点、最近的街道地址，以及包含该点的行政区域。每项数据均附带必须显示的来源署名。根据请求，还可以返回地点介绍和照片。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，每次调用按 want 中要求的最昂贵项目收取固定费用，即使没有查到结果也要收费。content 或 photos 在本次调用需要获取内容时按 /retrieval/poi/enrich 的费用计费；否则 address 按 /retrieval/geocode/forward 的费用计费。此前请求已获取的内容不收费，因此这类调用若同时要求 address，按地理编码费用计费。仅要求 entities、regions、boundaries 或 tenants 的调用免费。默认 want 包含 address，因此省略 want 会产生地理编码费用。

字段	类型	必填	默认值	说明
lat	数字	是		−90 至 90。目标点。
lng	数字	是		−180 至 180。
zoom	数字	否		0 至 24。地图缩放级别。
hint	对象	否		用户点击的对象（见下文）。
want	字符串数组	否	["entities", "address", "regions"]	要返回的数据部分（见下文）。
lang	字符串	否	"en"	content 使用的语言，不超过 16 个字符。

坐标点决定范围；提示信息只能用于选择。 提示信息从位于该点的对象中选择结果，绝不会改变目标位置：距离 lat、lng 超过 75 米的地点不会被返回，无论提示信息如何描述。

hint 字段	说明
id	Kaleidr 为地点分配的 ID：poi: 引用中冒号后面的部分。
name	地点名称，与地图标签中显示的一致。最多 200 个字符。该名称与指定位置处的地点进行精确匹配，并用于指定 content 对应的地点。如果 region_level 为 county、state 或 country，还会从该位置所处的相应层级区域中选择名称匹配的区域，匹配时忽略大小写和重音符号（对于州或国家，还包括距离该位置不超过 5 km 的区域）。如果名称未匹配任何区域，则不会产生变化。
category	地点类别。最多 100 个字符。用于 content。
region_level	使用 boundaries 时，仅返回该层级（city、county、state 或 country）区域的边界轮廓；不使用时，返回所有区域的边界轮廓。使用 name 时，regions 和 boundaries 中该层级的区域均由名称选定。
layer, wiki_title, ta_location_id, yelp_business_id, data_source	接受这些字段，但它们供 Kaleidr 自有应用使用；请勿传入。

want 值	添加的内容
entities	点击的地点，前提是 hint 指定了该位置处的一个地点。
address	最近的街道地址。
regions	包含该位置的城市和县（仅限美国）、州以及国家。如果该位置位于离岸不超过 5 km 的海域，则返回最近的州和国家。
boundaries	regions，每个区域均附带边界轮廓（指定 hint.region_level 时仅返回一个层级）。
content	地点描述内容：摘要、照片和链接。需要地点名称，可来自点击的地点或 hint.name。
photos	仅返回地点照片。费用与 content 相同。
tenants	返回该位置附近有名称的地点，按距离从近到远排序，即建筑物内的商户。你的应用应只保留位于所显示建筑物轮廓范围内的地点。

curl -s https://api.kaleidr.com/inference-api/b2b/v1/spot \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 40.7484,
    "lng": -73.9857,
    "zoom": 17,
    "hint": {"name": "Empire State Building", "category": "landmark"},
    "want": ["entities", "address", "regions"]
  }'

含示例值的简化响应：

{
  "spot": { "lat": 40.7484, "lng": -73.9857, "zoom": 17 },
  "entities": [
    {
      "ref": "poi:3f1c2a9e-…",
      "kind": "poi",
      "role": "clicked",
      "name": { "value": "Empire State Building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
      "at": { "lat": 40.74844, "lng": -73.98566 },
      "facts": {
        "category": { "value": "landmark_and_historical_building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
        "website": { "value": "https://www.esbnyc.com", "license": "CDLA-Permissive-2.0", "attr": "a1" }
      }
    }
  ],
  "address": {
    "ref": "address:ka1…",
    "line": { "value": "20 W 34th St, New York, NY 10001", "license": "CDLA-Permissive-2.0", "attr": "a2" },
    "at": { "lat": 40.7484, "lng": -73.9857 }
  },
  "regions": [
    {
      "ref": "region:tiger:3651000",
      "kind": "region",
      "level": "city",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 40.6976, "lng": -73.9795 }
    },
    {
      "ref": "region:tiger:36",
      "kind": "region",
      "level": "state",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 42.7559, "lng": -75.8099 }
    }
  ],
  "attributions": {
    "a1": { "text": "© Overture Maps Foundation", "license": "CDLA-Permissive-2.0" },
    "a2": { "text": "Address data from the NYC Department of City Planning.", "license": "CDLA-Permissive-2.0" },
    "a3": { "text": "U.S. Census Bureau, TIGER/Line", "license": "LicenseRef-Public-Domain" }
  },
  "withheld": ["building_facts"]
}

字段	含义
spot	发送的坐标点：{ lat, lng, zoom }。
entities	用户点击的地点；若请求了租户数据，还包含建筑内商家，否则为空数组。每项包含 ref、kind（点击的地点为 "poi"、建筑内商家为 "tenant"）、role（"clicked" 或 "inside"）、name、at（地点自己的坐标 { lat, lng }）和 facts（category，以及在已知时点击地点的 website）。商家的 ref 是 poi: 引用，因此也能生成其介绍流。忽略未知 kind 类型的实体。
address	最近的街道地址，或 null：{ ref, line, at }。
regions	包含该点的行政区域，从最小区域开始。每项包含 ref、kind（"region"）、level（city、county、state 或 country）、name 和 label（用于放置区域名称的点 { lat, lng }，或 null）。当 want: ["boundaries"] 时，还包含 geometry，即 GeoJSON 格式的区域轮廓。
content	当 want 包含 content 或 photos、地点名称已知且内容允许返回时才提供。对应 /retrieval/poi/enrich 的对象（字段），或仅请求 photos 时的 { photos, source, cached }，并增加 license 和 attr。无法检索内容时可能为 null。
attributions	此响应的来源署名：{ text, license }，使用各数据项的 attr 作为键。
withheld	按内容类型列出因许可限制而没有返回的数据；未省略任何内容时为空数组。

ref 用于在 /spot/overview/stream 中指定对象：poi:<id> 表示地点、address:<id> 表示地址、region:<source>:<id> 表示行政区域（<source> 为 tiger、nuts 或 ne）。Kaleidr 自有应用还使用 building:<id>，但 API 不会返回此类引用。应将引用视为不透明字符串。

显示每个值的来源署名

每个数据集值都是 { value, license, attr } 对象，分别表示数据值、许可协议以及指向 attributions 的键。无论在哪里展示数据，都必须同时提供 attributions[attr].text，可置于旁边或在可访问的来源信息区中。同一响应可能包含多个数据来源，因此只对整个响应显示单一署名并不够。存储或转发数据时，务必保留相应的 license 和来源署名。

content 也通过其自身的 attr 进行来源署名。标记为 live_only: true 的值只能向当前用户显示，不得存储或转发。

每种许可证的要求见数据许可证。

API 不返回的内容

Kaleidr 自有应用在一个地点显示的信息多于 API，因为有些数据的许可不允许用于其他网站：

• 受 ODbL 约束的 OpenStreetMap 派生数据： 建筑事实信息（楼层数、高度、类别）。建筑介绍同样无法通过 API 提供。
• 第三方提供商的结果： 地理编码服务的地址查询，以及 Yelp 和 Tripadvisor 的评分、评论和照片。

withheld 用于区分“此处没有已知数据”和“此数据无法通过 API 提供”。它只列出数据类别，不包含具体值：当点位于建筑内时可能出现 building_facts；当地点仅有的内容不能通过 API 返回时可能出现 content。其他条目也以相同方式标识响应中被省略的部分。

POST /spot 的错误：

状态码	错误代码	触发条件
413	request_too_large	请求体超过 2 MiB。
422	参数校验	缺少 lat 或 lng，或坐标超出范围；zoom 不在 0 至 24 范围内；want 包含未知值；字段过长或格式有误。
429	quota_exceeded	AI 积分池不足以支付请求。

无法查询的部分将以空值（null 或 []）返回，但调用仍会计费。

POST /spot/overview/stream

流式返回 /spot 所返回对象的简短文字介绍，该对象通过 ref 指定。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，按使用的令牌数计费。每次请求都会重新生成介绍。 响应：text/event-stream，通常先发送一个包含地点完整名称（如 "Springfield, Ohio, United States of America"）的 place 帧，然后是地点摘要数据帧；参见摘要与按钮数据流。

字段	类型	必填	默认值	说明
ref	字符串	是		/spot 响应中的 ref，最长 128 个字符，或 place:（见下文）。
lat、lng	数字	是		此前发送给 /spot 的坐标点。
lang	字符串	否	"en"	介绍文字的语言，不超过 16 个字符。
hint	对象	仅 place: 需要		{ name, category? }：要描述的名称。

ref	介绍对象
poi:<id>	地点。
region:<source>:<id>	行政区域。
place:	Kaleidr 没有记录的具名对象，例如 /spot 未返回实体的地点。请在 hint.name 中提供名称。
address:<id>、building:<id>	无法通过 API 提供：数据流会返回 error 事件。参见API 不返回的内容。

系统会在 lat、lng 位置重新查找对象，因此不会直接将请求中的描述视为事实。距离指定点超过 75 米的 poi: 引用、不包含该点的 region: 引用，以及没有 hint.name 的 place:，也都会收到 error 事件。

curl -N https://api.kaleidr.com/inference-api/b2b/v1/spot/overview/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "poi:3f1c2a9e-…", "lat": 40.7484, "lng": -73.9857, "lang": "en"}'

无法描述的引用会返回此数据帧，而不是摘要。它包含 ref，不包含 partial_text：

event: error
data: {"type": "error", "message": "Nothing to describe here.", "ref": "address:ka1…"}

状态码	错误代码	触发条件
413	request_too_large	请求体超过 2 MiB。
422	参数校验	ref 格式不符合上述任一形式，缺少 lat 或 lng 或坐标超出范围，或 lang 超过 16 个字符。
429	quota_exceeded	AI 积分池不足以支付请求。

从已弃用端点迁移

GET /retrieval/poi/enrich 和 POST /chat/summary/stream 已弃用。这两个端点在 2027-01-15 前仍按原方式响应，此日期之后可能随时移除。其响应头会标明弃用信息；Deprecation 将弃用日期 2026-10-16 表示为 Unix 时间戳：

Deprecation: @1792108800
Sunset: Fri, 15 Jan 2027 00:00:00 GMT
Link: </inference-api/b2b/v1/spot>; rel="successor-version"

/chat/summary/stream 的 Link 响应头指向 /inference-api/b2b/v1/spot/overview/stream。记录 Sunset 响应头，以识别仍在使用的旧调用。

从 GET /retrieval/poi/enrich 迁移到 POST /spot：

原方式	新方式
lat、lon（查询参数）	lat、lng（请求体）。注意字段名变化。
name、category	hint.name、hint.category
lang	lang，最长 16 个字符
完整查询	want: ["content"]
photos_only=true	want: ["photos"]
radius、dataSource、ta_location_id、regionLevel	省略。
响应体	content：原对象，另增加 live_only
attribution	content.attribution

费用相同或更低：/spot 不对此前请求已获取的内容收费。查询按 want 中最昂贵的项目计费，因此当本次调用需要获取内容时，将 entities、address 或 regions 添加到 want，即可在同一次调用中免费获取这些内容。

从 POST /chat/summary/stream 迁移到 POST /spot/overview/stream：

原方式	新方式
地点：location、building_properties.name、.category	使用坐标点和 hint: { name, category } 调用 /spot，然后以相同的 lat 和 lng 对 entities 中地点的 ref 获取介绍流。若 entities 为空，则发送 ref: "place:" 和相同的 hint。
building_properties.pid	ref: "poi:<id>"
lang	lang，最长 16 个字符
max_tokens	省略。
建筑：type: "building" 及其字段	没有替代端点。建筑介绍无法通过 API 提供。
数据帧	地点简介的数据帧，前面新增一个说明地点名称的 place 帧。

GET /retrieval/poi/enrich

已弃用

此端点已弃用，可能在 2027-01-15 之后移除。请改用 POST /spot，并设置 want: ["content"]。参见弃用端点迁移指南。

返回某个地点的说明内容：标题、摘要、照片和链接。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，按次收取固定费用。无论是否找到内容都会计费。

参数	类型	必填	默认值	说明
lat	数字	是		地点纬度。
lon	数字	是		地点经度。注意字段名是 lon，不是 lng。
name	字符串	否		地点名称。建议提供，单独使用坐标点往往找不到结果。
category	字符串	否		place 事件中给出的地点类别。
radius	整数	否	250	点位周围的搜索半径，单位为米。
lang	字符串	否	"en"	内容的语言。
photos_only	布尔值	否	false	仅返回照片（响应体更小，见下文）。
dataSource、ta_location_id、regionLevel	字符串	否		接受这些提示信息，但它们供 Kaleidr 自有应用使用；请省略。

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/poi/enrich \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "lat=48.8606" \
  --data-urlencode "lon=2.3376" \
  --data-urlencode "name=Louvre Museum" \
  --data-urlencode "category=museum"

{
  "source": "wikipedia",
  "found": true,
  "title": "Louvre",
  "photos": ["https://upload.wikimedia.org/…/Louvre_Museum.jpg"],
  "summary": "The Louvre is a national art museum in Paris, France…",
  "rating": null,
  "phone": null,
  "hours": null,
  "reviews": [],
  "url": "https://en.wikipedia.org/wiki/Louvre",
  "attribution": ["Wikipedia"]
}

字段	类型	含义
source	字符串	内容来源。"omitted" 表示该地点有内容，但不能通过 API 返回（见下文）。
found	布尔值	未找到内容时为 false，其余字段为空。
title	字符串	来源中的地点标题。
summary	字符串或 null	简短介绍。
photos	URL 数组	可能为空。
url	字符串或 null	来源页面链接。
attribution	字符串数组	需要署名的来源，如 ["Wikipedia"]。展示内容时须同时显示。
rating、phone、hours、reviews		可能为 null 或空值。API 不返回授权供应商的评分和评论。
unverified	布尔值	可选。地点匹配不确定时为 true。

当 photos_only=true 时，响应为 { "photos": […], "source": "…", "cached": false }。

被保留、不返回的内容。 部分内容仅获许可用于 Kaleidr 自有应用。如果某地点只有此类内容，API 会返回 200、"source": "omitted"、"found": false，且不提供具体内容。请求仍会计费。参见数据许可。

状态码	错误代码	触发条件
422	参数校验	缺少 lat 或 lon，或其值不是数字。
429	quota_exceeded	AI 积分池不足以支付请求。
500	An internal error occurred. Please try again.	查询失败，但仍会计费。

---

POST /chat/summary/stream

已弃用

此端点已弃用，可能在 2027-01-15 之后移除。请改用 POST /spot/overview/stream。建筑简介没有替代端点。参见弃用端点迁移指南。

流式生成单个地点或建筑物的简短文字摘要，用于 Kaleidr Chat 的地点卡片。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，按使用的令牌数计费。每次请求都会重新生成摘要。 响应：text/event-stream。参见摘要与按钮数据流。

请求正文中的 type 决定摘要类型。

建筑物（"type": "building"）：

字段	类型	必填	说明
type	字符串	是	"building"。
address	字符串	是	建筑完整地址，最多 500 个字符。
lat、lng	数字	否	建筑坐标。
building_levels	整数	否	楼层数（如已知）。
building_height_m	数字	否	建筑高度（米，如已知）。
tenant_names	字符串数组	否	建筑内商家名称，最多 100 个，每个不超过 200 个字符。
poi_count	整数	否	建筑内地点数量。
lang	字符串	否	默认值为 "en"，最多 35 个字符。

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/summary/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "building", "address": "20 W 34th St, New York, NY 10001", "lat": 40.7484, "lng": -73.9857}'

event: start
data: {"type": "start", "address": "20 W 34th St, New York, NY 10001"}

data: {"text": "A landmark office tower in Midtown Manhattan"}

event: end
data: {"type": "end", "full_text": "A landmark office tower in Midtown Manhattan…", "parsed": {"…": "…"}, "total_tokens": 910}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 185133, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

地点请求（未提供 type，或其值为 "poi"）：请求体可以包含 location（对象 { lat, lng }）、building_properties（对象）、lang 和 max_tokens（整数）。此形式专为 Kaleidr 自有面板设计，具体字段含义尚未成为正式公开协议。如果从自有代码中查询地点，建议使用 /chat/control/stream。

地点字段	限制
building_properties.name、.type、.category、.poi_type	每个最多 200 个字符
building_properties.pid	128 个字符
building_properties.event 中的各文本字段	4,000 个字符
lang	35 个字符
max_tokens	超过端点默认值时会降至默认值，不能要求生成更长的简介。

这两种请求形式只读取这里列出的字段。 请求体中的其他字段会被忽略。如果某字段超过长度限制，系统会在生成介绍之前返回 422 field_too_long。

状态码	错误代码	触发条件
413	request_too_large	请求体超过 2 MiB。
422	field_too_long	某字段超长，或 tenant_names 包含超过 100 个条目。响应体为 {"detail": "field_too_long"}。
500	Summary stream error	无法读取请求体，或建筑请求没有 address。此端点对其他格式不正确的请求体也返回 500，而不是 422。
429	quota_exceeded	AI 积分池不足以支付请求。

POST /chat/button/stream

流式回答关于某个地点的单个问题，例如“营业时间是什么？”。它用于 Kaleidr Chat 地点卡片中的提问按钮。此端点不保留对话历史，每次调用都是独立的。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：ai. **费用：**AI 积分，按使用的令牌数计费。 响应：text/event-stream。参见摘要与按钮数据流。

字段	类型	必填	默认值	说明
query	字符串	是		具体问题，最多 4,000 个字符。
place_name	字符串	否		被询问的地点名称，最多 200 个字符。
place_type	字符串	否		地点类别，最多 200 个字符。
address	字符串	否		地点地址，最多 500 个字符。
location	对象 { lat, lng }	否		地点坐标。
lang	字符串	否	"en"	回答语言，最多 35 个字符。
description	字符串	否		已知的地点说明，最多 4,000 个字符。
website	字符串	否		地点网站（如已知），最多 2,048 个字符。
stores_preview	{ name } 对象数组	否		已知位于该地点的商家，最多 50 个，每项的 name 最多 200 个字符。其他成员会被忽略。
button_id、session_id、place_id	字符串	否		用于关联请求的自定义标识符，每个最长 128 个字符。

本表未列出的字段会被忽略。长度超限的字段会在生成任何答案之前被以 422 field_too_long 拒绝。

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/button/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is this place known for?",
    "place_name": "Louvre Museum",
    "place_type": "museum",
    "location": {"lat": 48.8606, "lng": 2.3376}
  }'

event: start
data: {"type": "start", "query_type": "…"}

data: {"text": "The Louvre is best known for"}

event: end
data: {"type": "end", "full_text": "The Louvre is best known for…", "reply": "The Louvre is best known for…", "query_type": "…", "first_token_ms": 820, "total_ms": 3900, "total_tokens": 640}

状态码	错误代码	触发条件
413	request_too_large	请求体超过 2 MiB。
422	field_too_long	某字段超长，或 stores_preview 超过 50 项。响应体为 {"detail": "field_too_long"}。
500	Button chat stream error	无法读取请求体或没有 query。此端点对其他格式不正确的请求体也返回 500，而不是 422。
429	quota_exceeded	AI 积分池不足以支付请求。

---

POST /design/analyze

检查表格的列和样本，并推荐适当的地图展示方式。

嵌入式 Editor 不会调用设计端点。这些端点是供您自己的工具使用的 REST 接口。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：design. **费用：**AI 积分，每次成功调用收取固定费用。失败的调用不收费。

字段	类型	必填	说明
columns	字符串数组	是	1 至 256 个列名，不能重复。
sampleRows	对象数组	否	最多 1,000 行，每行使用列名作为对象键。
datasetName	字符串	否	最多 512 个字符。
rowCount	整数	否	整个数据表的行数，不小于 0。
userGoal	字符串	否	最多 1,000 个字符：地图需要展示什么。
supportedStyles	字符串数组	否	可选的样式 ID，由小写字母单词和连字符组成。

字段名使用 camelCase。未知字段将被忽略。

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/analyze \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetName": "stores.csv",
    "columns": ["name", "lat", "lng", "revenue"],
    "sampleRows": [
      {"name": "Downtown", "lat": 40.7128, "lng": -74.0060, "revenue": 120000},
      {"name": "Uptown", "lat": 40.7831, "lng": -73.9712, "revenue": 86000}
    ],
    "rowCount": 240,
    "userGoal": "Show which stores earn the most"
  }'

{
  "datasetProfile": { "…": "what was detected in each column" },
  "designPlan": { "…": "the recommended style, theme and reasoning" },
  "issues": [],
  "recommendation": { "…": "…" },
  "suggestedConfig": { "…": "…" },
  "explanation": "…"
}

请读取 designPlan；它可能为 null。recommendation、suggestedConfig 和 explanation 是为了兼容性而保留、计划移除的旧字段，不应再依赖。issues 列出在数据中检测到的问题。

状态码	错误代码	触发条件
413	request_too_large	请求体超过 5 MiB。/design/apply-direct 同样适用此限制。
422	参数校验	columns 缺失、为空、过长、包含重复项，或超出上述任一限制。
429	quota_exceeded	AI 积分池不足以支付请求。
500	map_design_analyze_failed	分析失败，不计费。

POST /design/apply-direct

使用表格和所选样式直接创建地图图层，无需分析。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：design。**费用：**无。

字段	类型	必填	说明
style	字符串	是	长度为 1 至 64 个字符的样式 ID，可从 /design/styles 获取。
config	对象	是	包含 location、metric 和 visual 成员的对象。必须提供 location.mode（"coordinates" 或 "region"）以及 visual.layerName；其他子字段尚未正式记录。
table	对象	是	{ fileName?, columns[], rows[] }。每行是列名与数值的映射，但每个值必须是 JSON 字符串：发送 "120000"，而不是 120000。含数字值或 null 的行将被 422 拒绝。
layerLabel	字符串	是	图层显示名称，长度为 1 至 512 个字符。
themePackId	字符串	否	来自 /design/themes 的主题 ID。未知值会被忽略。
datasetSource	对象	否	{ label, url? }：数据发布方，用于图层来源署名。
datasetId	字符串	否	最多 128 个字符，作为图层 ID 使用。
year	整数	否	1800 至 2100。

响应始终包含 status：

{ "status": "applied", "message": null, "spec": { "…": "a partial map specification" } }

status	含义
applied	spec 包含已生成的图层。
unsupported-style	无法根据此数据生成指定样式。message 会说明原因。
insufficient-data	数据表缺少样式所需的信息（例如坐标列）。message 会解释原因。

这三种响应的状态码都是 200，请检查 status。

GET /design/styles, /design/samples, /design/themes

三个只读目录：可用地图样式、示例地图和主题包。

**身份验证：**服务器密钥、会话令牌或旧版密钥。权限范围：design. **费用：**无。这些调用计入密钥的每分钟请求次数，但不计入并发请求数。

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer $KALEIDR_KEY"

每个响应均将列表放在单个键之下：

{ "styles": [ { "…": "…" } ] }

/design/samples 返回 { "samples": [ … ] }，/design/themes 返回 { "themes": [ … ] }。

---

所有运行时端点共有的错误

除两个会话交换端点外，所有端点在执行各自处理之前都可能返回这些错误。检查顺序如下。

顺序	状态码	错误代码	触发条件
1	401	Invalid or missing API key	未提供凭证，或密钥未知、已撤销或过期。
2	401	publishable_requires_session	直接提供了可公开密钥，需要先交换为会话令牌。
2	403	server_key_in_browser	带有 Origin 请求头的服务器密钥请求。
2	403	session_origin_mismatch	会话令牌从其他来源使用。
2	403	ip_not_allowed	带 IP 白名单的服务器密钥或旧版密钥从未获允许的地址发起调用。
3	403	insufficient_scope	密钥缺少该端点所需权限范围。
3	403	tier_capability_not_allowed	密钥具有相应权限范围，但当前套餐不再包含此功能。
3	403	product_not_allowed	仅限特定产品的服务器密钥或旧版密钥调用了其他产品的端点。参见限制密钥用途。
4	429	quota_exceeded	仅收费端点：积分池或密钥月度上限不足以支付此调用。
5	429	visitor_limit_reached	仅已发布地图的访问者会话：访问者的请求次数过多。
6	429	rate_limited	此密钥每分钟的请求额度已用尽。
7	429	b2b_overloaded、org_overloaded	同时处理的请求数量过多。

如果请求体超过大小限制，系统将返回 413 request_too_large：普通端点限制为 2 MiB，/design/* 端点为 5 MiB。如果请求声明了内容长度，则会在上述其他检查之前拒绝。

各响应正文及处理方法见错误参考和配额与速率限制。

相关内容

• 服务器快速入门：逐步完成首次调用。
• SSE 传输协议：数据流的所有事件。
• 读取数据流：完整客户端示例。
• 数据许可：需要展示的来源署名。