Content Delivery API

Content Delivery API 是专为外部前端与移动 App 设计的公开 HTTP API，直接挂载在您网站自己的网址下。当您在数据集合、博客、页面管理或在线表单发布内容后，任何前端框架（Next.js、Astro、Remix、Nuxt、SvelteKit）都可以直接调用，不需要在前端保管密钥，并由全球边缘缓存提供毫秒级响应。

完整端点、参数与错误码参考（SSOT）：所有端点路径、查询参数、响应结构、速率限制 Header 与错误码，皆由 OpenAPI 3.1 规范自动生成于 Content Delivery API 参考页（您也可以直接从您的网站下载 https://{您的网站}/api/v1/openapi.json）。本文专注于说明平台层的设计概念。

三套 API 的分工

两层网址：为什么推荐使用永久系统网址？

您的网站同时拥有两种可调用 Content Delivery API 的网址：

1. 永久系统网址（https://s-xxxxxxxxxxxx.kanorio.com/api/v1）：建站当下即配发，永久不变。即使您尚未发布 Kanorio 托管页面（仅在“网站设置 › 开发者”开启“未发布网站时仍启用 API 服务”），或未来把自定义域名的 DNS 指向 Vercel／Cloudflare Pages，这组系统网址依然永远有效。
2. 公开子域名或自定义域名（https://您的子域名.kanorio.com/api/v1）：当托管网站已发布时，也可直接通过公开域名调用。

搜索引擎防护：所有 /api/v1/* 响应皆自动带上 X-Robots-Tag: noindex Header，防止搜索引擎将 JSON 端点当成网页收录而稀释您网站的 SEO 权重。

为什么采用顶层 assets 媒体对照表？

在许多传统 CMS 中，图片字段若只存一串 ID，前端必须再发第二次请求才能拿到网址；若直接把图片网址写死在字段内，当站主在媒体库替换图片或修改替代文字（alt）时，所有文章里的旧网址就会失效。

因此，Kanorio 在 /collections/{key}/items、/pages/{slug} 与 /globals/* 的响应顶层统一附上 assets 对照表：

• 字段值保持干净：项目内的 image、file 字段维持存 assetId 字符串（gallery 存 assetId[]）。
• 一次解析所有引用媒体：顶层 assets[assetId] 自动附上最新的公开 CDN 网址（url）、原始宽高（width、height）、替代文字（alt）、文件类型，以及 16px WebP 模糊占位图（placeholder Data URL）。
• 响应式图片免设置：公开图片网址可直接加上 /w=400、/w=800、/w=1200、/w=1600 或 /w=1920 获取对应宽度的优化图片，搭配 placeholder 即可在 Next.js <Image blurDataURL={...} /> 实现零 CLS 加载。

跨域读取（CORS）与草稿预览令牌（knr_pv_）

1. 允许的来源（CORS 白名单）

• 若您在 Next.js Server Component、Astro 构建阶段或后端服务器调用 API，属于服务器对服务器请求，不需要设置 CORS。
• 若您从外部网站的浏览器端直接 fetch（例如即时搜索或提交表单），请到后台“网站设置 › 开发者”将外部前端的 Origin（如 https://www.example.com）加入“允许的来源”。本地开发 http://localhost:* 默认永远允许。
• 重要观念：CORS 白名单仅控制浏览器是否放行跨源读取，不是授权边界；未发布的草稿在数据库查询层即完全隔离。

2. 在自建前端安全预览草稿（X-Kanorio-Preview）

当编辑者在后台修改了文章或页面草稿、想在外部前端预览尚未发布的画面时：

• 前往“网站设置 › 开发者”建立一把 knr_pv_ 开头的只读预览令牌（或由 AI 调用 site.create_preview_token）。
• 在您外部前端的服务器端（如 Next.js Draft Mode）带上 Header X-Kanorio-Preview: knr_pv_您的预览令牌（或使用 @kanorio/sdk 的 previewToken 选项）。
• 预览请求会在边缘节点直接完成 HMAC 验签、旁路所有公开缓存（Cache-Control: private, no-store），并返回最新草稿内容。

版本键边缘缓存与 X-Kanorio-Cache-Tags

Content Delivery API 不限制每月读取次数、也不收 API 流量费，关键在于两层版本键缓存与缓存标签设计：

1. 自动版本推进：每当您在后台或通过 AI 发布任何内容，网站的 publicVersion 会自动推进，边缘缓存在数秒内立即切换至新版，同时支持弱 ETag 与 If-None-Match（内容未变时返回 304 Not Modified）。
2. 精准缓存标签（X-Kanorio-Cache-Tags）：每个响应都会带上结构化标签（如 site:{siteId}、collection:blog、item:{itemId}、pages、globals、redirects），与 Payload 中的 data.cacheTags 完全对齐，一行代码就能在 Next.js 完成按需更新。

相关文档