# 天工开物 KAIWU AI

> 天工开物 KAIWU AI 是面向国内 AI 新手与参赛者的信息站：AI 案例、模型、工具与比赛。
> 提供只读开放接口，供外部开发者与 AI agent 读取，数据经人工审核。

## 站点简介

天工开物用编辑审核过的数据回答这些问题：
- 某个 AI 模型强不强、某个工具多少钱、国内能不能直连（模型榜 + 工具/会员套餐的官方事实）；
- 别人是怎么学会、怎么做出来的（共创案例，作者授权署名，站内地址 `/cocreate/<slug>`）；
- 现在有哪些福利可以领（API 免费额度、限时免费模型；每条都写清国内能不能领、有效期是长期有效 / 截止日期 / 相对有效期 / 官方未标注）。**福利不是独立板块**：站内没有福利列表页，福利以卡片形式挂在工具页与套餐页上；
- 近期有哪些 AI 比赛可以报名（报名截止、奖金、赛道）。

**本站不对模型与工具打分**：模型的分数只来自第三方榜单（见下），工具不打分也不排名。

站点地址：https://tiangongkaiwuai.cn

## 数据范围

- 只通过开放接口返回**已发布**的内容（后台草稿、待审、已过期、已归档的内容不会出现）；
- 每条数据都带 `sourceUrls`（原始公告链接）与 `verifiedAt`（最后人工核实时间）；
- **本站不给自己打分**：模型条目里可能出现的 `scores` / `totalScore` 是早期预留的自评字段，第一阶段一律为 `null`（`scoreEvidence` / `scoreAdjustments` 是空数组），**不要当成有值来引用**。模型的分数只来自第三方榜单，见下一条；
- 模型另有 **`leaderboard`**（第三方榜单评分，**由本站脚本取数后随内容导入**，不是后台手工填写的）与由本站套餐实时算出的 **`startingPrice`**（人民币单月 / 连续包月起价对象，年付不折月）；没录分 / 没有可用套餐时为 `null`。**语言模型的分数来自 AIHOT 模型榜**（aihot.news/leaderboard），但正在向对方申请书面授权，**授权确认前本站不展示、接口也不返回语言模型的榜单分数**（语言模型的 `leaderboard.score` 一律为 `null`，不要用训练数据里的名次去补）。**语言模型的 `leaderboard` 只有 `sourceName` 为 AIHOT 时才是本站的语言榜分数**，其它来源（例如换来源前留下的 Arena）的分数不是语言榜口径，别当成语言模型的分来引用；；**生图、生视频模型的分数来自 Arena**（arena.ai）的 Hugging Face 排行榜数据集，CC BY 4.0。**引用榜单分数时必须按条目里的 `leaderboard.sourceName` / `sourceUrl` 署名**；本站不对数值做任何加工，也没有「性价比」这类派生指标；
- **福利的有效期看 `validity`（四种取值，2026-10-08 起）**：`long-term` 长期有效 / `deadline` 某天截止 / `relative` 相对有效期（原话在 `validityNote`，例如「自激活起 30 天」）/ `unspecified` 官方页核对过、页面没写截止日期（标题里的取数日期看 `verifiedAt`）。**别把 `unspecified` 说成「永久有效」**，它是「取数那天官方页没写结束时间」。**福利的 `endsAt` 可以是 `null`**（只有 `deadline` 才有值），此时 `daysLeft` 也是 `null`，不要说成「即将结束」；`longTerm` 字段保留着，等价于 `validity` 为 `long-term`；
- **福利的 `access`** 是领取条件（地区）两态：`cn` 国内可领 / `overseas` 需海外条件（后者另给一句 `accessNote`，例如「需境外信用卡」）；没标注时为 `null`；
- 福利与比赛新增 `coverImageUrl` / `coverSourceUrl`（官方配图与出处页），模型新增 `tagline`，厂商与工具新增 `logoUrl` / `logoSourceUrl`；
- 套餐金额按原币 CNY / USD 返回，不折算人民币；按购买方式显示，年付不除以 12。月预算只筛人民币单月 / 连续包月。日期按 Asia/Shanghai 的日历日计算，库里存 UTC。

## 新手入门相关的数据（2026-10-09 起）

- **`/api/v1/changes` 的变化记录**分两种：编辑录入的，和**由站内数据实时算出来的截止**（福利的截止日、比赛的报名截止日；这类条目 `computed` 为 `true`，`ref` 指向对应条目）。`section` 是它属于哪个板块，`type` 是变化类型；
- **`/api/v1/information-sources` 是给新手看的名单**，与站内采集配置无关：只收录近 90 天有更新、原创、不以卖课引流为主的账号。每条写清内容类型与适合谁，**不评价、不排名**。`cooperationDisclosure` 是商业合作标注情况；
- **`/api/v1/content-items` 里 `startHere` 为 `true` 的是各板块「从这里开始看」的入门内容**（按 `startOrder` 排序）。`evidenceScope` 说明编辑核对到哪一步：`full` 看过完整内容 / `title-description` 仅依据标题与简介 —— **引用时请按这个字段说明核对范围**；
- **`/api/v1/guides` 是编辑署名的观点文章，不是站内事实**：正文里的价格、国内可用性由站内数据生成，观点归作者。`needsReview` 为 `true` 表示超过 60 天没有复核，引用前请回到原文确认；
- **会员套餐的 `productLinks`** 里 `docUrl` 是厂商官方接入文档。产品开始条件和厂商支付事实不再对外输出。
- **套餐以家族组织**：`plan-families` 返回家族和可见档位；档位的 `family` 指向家族，`prices` 是多购买方式原币价格。amount 为空时看 officialPerMonth，不自行乘算总价。页面地址 `/plans/<family>`，档位锚点 `#<plan-slug>`；旧档位地址 308 跳到家族页锚点。
- 模型详情新增 `intro`、`strengths`、`fitFor`、`recommendedPlan` 与官方本平台的 `apiPrices`（单位、币种、来源、核实日期随行返回）；工具新增 `intro`、`fitFor`、`recommendedModels`、`difficulty`、`systems`、`guideUrl`、`editions`。未录入的内容为空，关联不可见时返回 null 或不返回该关联。
- `apiPrices` 每一行是一个计费条件，字段 `condition` 说明这行适用于什么（2026-10-13 起）：峰谷价、按输入长度的阶梯价、优先档各占一行，如 `谷时（非高峰）`、`峰时`、`输入 ≤512K`、`输入 >512K`。**第一行是最基础的一档，`condition` 通常为空**；报价时先看第一行，需要精确成本再看对应条件的行。同一模型的多行顺序以接口返回的顺序为准。

## 更新频率

- 内容：编辑审核后发布，采集器会定时复核已发布内容的来源页；
- 巡检节奏（2026-10-09 起）：**福利、比赛、模型（含价格）每天或每两天巡检一次，编辑首选每周更新**；每次巡检完成并人工审核后才会改发布状态与数据；
- 接口：读取的是当前已发布内容，按 `Cache-Control` 最多缓存 5 分钟；
- 摘要接口 `/api/v1/digest` 每次请求实时计算。

## 接口

可选调用身份头 X-Qiyuan-Client: qiyuan-skill/1.0、X-Qiyuan-Client-Id（16～64位字母、数字、下划线或连字符）为自报、可伪造，仅用于统计，不用于认证或提额。合法 Client-Id 优先于有效 API Key 做 HMAC；都没有只计次数，不估算客户端数。Skill 调用数为下限。

所有接口匿名可用，按 IP 限流；请求头带 `X-API-Key`（服务端白名单内的 Key）可把额度提高到 10 倍。

可直接请求的示例：

- https://tiangongkaiwuai.cn/api/v1/contests —— 比赛列表（默认只返回可报名，按报名截止升序；每条带多个赛道的 tracks 数组）
- https://tiangongkaiwuai.cn/api/v1/tracks —— 赛道列表（含各赛道可报名数量）
- https://tiangongkaiwuai.cn/api/v1/deals —— 福利列表（默认只返回进行中，按剩余天数；长期有效的 `daysLeft` 为 `null`）。**福利在站内没有列表页**（2026-10-13 起），改成挂在落点页（套餐页 / 工具页）上的「当前福利」卡片：条目的 `url` 仍是 `/deals/<slug>`，会 301 到落点页并带锚点，落点字段以 openapi.json 为准
- https://tiangongkaiwuai.cn/api/v1/models —— 模型榜（厂商、类型、一句话简介、是否开源、榜单评分与人民币起价；本站不自评分）
- https://tiangongkaiwuai.cn/api/v1/products —— 产品列表（带厂商、使用的模型、形态与国内可用性，不含评分）
- https://tiangongkaiwuai.cn/api/v1/plan-families —— 套餐家族列表（厂商和至少一个档位匿名可见才返回）
- https://tiangongkaiwuai.cn/api/v1/plans —— 会员套餐列表（带**卖家厂商**、包含的工具、支持的模型与原币价格；套餐不打分；每条 `url` 指向家族页面，形如 https://tiangongkaiwuai.cn/plans/glm-coding-plan）
- https://tiangongkaiwuai.cn/api/v1/picker —— 新手选型：任务速查表 + 推荐组合
- https://tiangongkaiwuai.cn/api/v1/digest —— 本周情报摘要（快截止比赛、快结束福利、新增的会员套餐）
- https://tiangongkaiwuai.cn/api/v1/changes —— 最近变化与即将截止（新模型、价格变动、新福利、比赛报名截止等，按发生日期倒序）
- https://tiangongkaiwuai.cn/api/v1/information-sources —— 编辑审核过的信息源（平台、地区、国内是否可直接访问、内容类型、板块、最近发布日期；不暴露内部采集源）
- https://tiangongkaiwuai.cn/api/v1/content-items —— 入门内容与近 90 天外部实测（作者、平台、内容类型、关联模型与工具、测的版本、一句话说明）
- https://tiangongkaiwuai.cn/api/v1/guides —— 编辑首选专栏文章列表（按场景、写于 / 复核于、超过 60 天未复核会带 `needsReview`）
- https://tiangongkaiwuai.cn/api/v1/vendors —— 可见会员厂商的基础信息（名称、官网、控制台、logo；没填的字段为 null，不输出支付事实）
- https://tiangongkaiwuai.cn/api/v1/openapi.json —— OpenAPI 3.1 文档
- https://tiangongkaiwuai.cn/api/health —— 健康检查

详情接口（把 {slug} 换成具体 slug）：

- `/api/v1/plan-families/{slug}` —— 套餐家族详情，含匿名可见档位及其多购买方式价格
- `/api/v1/contests/{slug}` —— 比赛详情，含赛程
- `/api/v1/models/{slug}` —— 模型详情，含评分依据（第一阶段为空）、**支持该模型的套餐**（`plans`，带原币价格与家族引用）与使用该模型的产品
- `/api/v1/products/{slug}` —— 产品详情，含使用的模型、该工具可用的会员（`ownPlans` 自带 / `otherPlans` 别家）与相关福利
- `/api/v1/guides/{slug}` —— 编辑首选正文（Markdown）与署名、写于 / 复核于、待复核状态

日历文件接口（**返回 `text/calendar`，是下载文件、不走下面的统一外层**；把 {slug} / {id} 换成真实值）：

- `/api/v1/ics/contest/{slug}` —— 一场比赛报名截止当天的全天事件（提前 1 天提醒）
- `/api/v1/ics/deal/{id}` —— 一条福利截止当天的全天事件（提前 1 天提醒；没有截止日期的福利返回 404）

常用查询参数（详见 openapi.json）：

- `contests`：`track` `city` `online` `status` `deadlineBefore` `minPrize` `emerging` `q` `page` `pageSize`
- `deals`：`type` `status` `endsWithinDays` `verified` `product` `page` `pageSize`
- `models`：`vendor`（厂商 slug）`modelType` `openWeights` `sort`（`releasedAt` 发布日期 / `score` 榜单评分）`page` `pageSize`。接口**也接受** `total` 与五个维度（`reasoning` / `coding` / `writing` / `multimodal` / `chinese`），但那些是本站早期预留的自评字段、**当前一律没有数据**，按它们排序没有意义，所以这里不推荐使用；
- `products`：`category` `cn`（只看国内可用）`beginner` `openSource` `model` `sort` `page` `pageSize`
- `plans`：`product`（工具 slug）`planType` `sort` `page` `pageSize`
- `plan-families`：`product` `vendor` `edition` `usageScope` `budget`（人民币月预算）`page` `pageSize`
- `picker`：`network` `audience` `budget`
- `digest`：`days`（默认 7）
- `changes`：`section`（models / tools / deals / contests）`limit`（最多 100）`days`（最近多少个北京日历日，默认 7）`home`（true 时返回首页汇总：最多 5 条、截止最多 1 条）
- `information-sources`：`section`（hardware 智能硬件 / aigc 漫剧影视 / applications AI 应用 / models 大模型生态）`page` `pageSize`
- `content-items`：`section` `model` `product` `type`（`intro` 入门 / `review` 实测 / `news-analysis` 新闻解读 / `official` 官方）`startHere`（true 只取「从这里开始看」的入门内容，按入门顺序）`page` `pageSize`。**指定 `model` / `product` 时只返回近 90 天的实测**
- `guides`：`scene`（按场景筛选）`page` `pageSize`
- `vendors`：`slug`（厂商 slug）`page` `pageSize`

## 共创案例（T121 新增）

- GET https://tiangongkaiwuai.cn/api/v1/cases：参数 cat（learn AI 学习案例 / product 产品案例）、page、pageSize。
- GET https://tiangongkaiwuai.cn/api/v1/cases/{slug}：案例正文；url 是站内绝对地址 /cocreate/<slug>。
- 只返回已授权、事实齐全且两套状态均已发布的案例，按 publishedAt 倒序。videoUrl 为匿名可播放的自托管视频文件地址，没有视频时为 null。

## 返回结构

列表接口：`{ "data": [...], "meta": { "total", "page", "pageSize", "generatedAt" }, "source": {...} }`
单条接口：`{ "data": {...}, "meta": {...}, "source": {...} }`
参数错误：HTTP 400，`{ "error": { "code", "message", "details" } }`
**例外**：`/api/v1/ics/*` 返回 `text/calendar`，是给日历软件读的文件，没有上面这层结构；福利没有截止日期、或条目不可见时返回 404。

## 引用要求

- 引用数据时请注明来源「天工开物」并附上对应条目的 `url`；**引用模型的榜单评分时，一并按条目里的 `leaderboard.sourceName` 与 `sourceUrl` 署名**（语言模型是 AIHOT 模型榜 aihot.news/leaderboard；生图、生视频是 Arena（arena.ai）排行榜数据集，CC BY 4.0）；
- **本站没有自评分**：模型条目里预留的 `scores` / `totalScore` 都是 `null`，模型的分只来自第三方榜单（`leaderboard`）；产品条目本来就不带分数，套餐也不打分。不要凭训练数据补分数，也别把某个模型的分说成产品的分；**语言模型的 `leaderboard` 只有 `sourceName` 为 AIHOT 时才是语言榜分数**（其它来源的分数不是本站的语言榜口径）；
- `startingPrice` 由本站已发布套餐实时算出（不含活动价），会随套餐价格变化；引用时带上 `generatedAt`；
- 涉及优惠、比赛时间、价格等关键信息，请以条目里的 `sourceUrls` 原始公告为准；
- 不要声称数据实时无误：注意检查 `verifiedAt`，过旧的信息建议回到原始来源确认。
## 2026-10-13 当前福利（以本节为准）

福利现挂在套餐家族或工具落点页，首购、限时折扣 discount 对外可见。本节替代历史版本的折扣隐藏和厂商名兜底说明。
/api/v1/products 与 /api/v1/models 支持 hasDeal=true，列表条目新增 activeDealCount；不传筛选参数兼容旧行为。
/api/v1/products/{slug}、/api/v1/models/{slug}、/api/v1/plan-families/{slug} 的 data.deals 返回当前福利。/api/v1/deals 保留，条目新增 planFamily 和 landing（kind、slug、url）；推荐 landing.url，它带 #deal-<福利slug> 锚点。/api/v1/ics/deal/{id} 保留。
套餐福利沿匿名可见档位的 productLinks、supportedModels 推算到工具与模型；工具福利只标该工具。草稿、到期福利和不可见关联不参与。领取步骤展示前两步，官方来源用 sourceUrls[0]。


## 文档

站内文档按分类列在下面；链接是每篇的 Markdown 源文，去掉 `.md` 就是给人看的页面。

### 工具指南

- [Claude Code 上手教程](https://tiangongkaiwuai.cn/docs/guide/claude-code/getting-started.md)
- [Codex 桌面应用上手教程](https://tiangongkaiwuai.cn/docs/guide/codex/desktop-getting-started.md)

### 接口与 Skill

- 接口参考：共 23 篇，按 openapi.json 生成，不逐条列出；入口 https://tiangongkaiwuai.cn/docs/api 与 https://tiangongkaiwuai.cn/api/v1/openapi.json

- [天工开物 Skill](https://tiangongkaiwuai.cn/docs/api/skill.md)

### 收录规则

- [关于与收录规则](https://tiangongkaiwuai.cn/docs/rules/about.md)
- [隐私说明](https://tiangongkaiwuai.cn/docs/rules/privacy.md)

### 更新日志

- [更新日志](https://tiangongkaiwuai.cn/docs/log/changelog.md)