DEVELOPER API / V1

让内容
自动流入编辑台。

使用账户 API Key,把第三方系统产出的行业资讯、技术资料和观察文章提交到产业前沿。以 hashId 为唯一标识,重复提交即可更新同一篇资讯。

POST /api/v1/articles
$ curl -X POST \
  https://info.consensusai.tech/api/v1/articles \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hashId": "report-2026-001",
    "title": "液冷数据中心的下一站",
    "summary": "从风冷边界到冷板规模化……",
    "contentHtml": "<p>正文内容</p>",
    "categoryId": 2,
    "isUpdate": false
  }'
01 / QUICKSTART

快速开始

01

创建 API Key

登录编辑后台,打开「API Key」,创建一个属于当前账户的 Key。完整 Key 只显示一次。

02

查询分类

调用 GET /api/v1/categories 获取分类 ID 和 slug;如需归入合集,再查询 collections。

03

提交资讯

向 POST /api/v1/articles 发送 JSON。首次创建使用 isUpdate: false。

API Key 属于账户,不是平台公共 Key。

每个编辑/管理员账户管理自己的 Key。账户停用或 Key 被禁用后,使用该 Key 的请求会立即返回 401。

自动化集成可以直接读取 OpenAPI 3.1 规范,导入 Apifox、Postman 或代码生成器。

02 / AUTHENTICATION

认证

所有 /api/v1/* 接口都需要 API Key。推荐放在 Authorization 请求头:

Authorization: Bearer cyk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

也兼容 X-API-Key 请求头。请始终在服务端保存 Key,不要放进浏览器前端代码、URL 参数或公开仓库。

POSThttps://info.consensusai.tech/api/v1/articles
03 / SUBMIT

提交资讯

请求体为 JSON,Content-Type: application/json。成功创建返回 201,更新返回 200,响应中的 data.url 是前台可访问地址。

201 Created · application/json
{
  "ok": true,
  "data": {
    "action": "created",
    "id": 42,
    "hashId": "report-2026-001",
    "status": "published",
    "author": "产业研究部",
    "url": "https://info.consensusai.tech/news/42",
    "publishedAt": "2026-11-17T02:00:00.000Z"
  }
}
04 / FIELDS

字段说明

字段类型必填说明
hashIdstring是资讯唯一标识,1–128 位字母、数字、点、下划线、冒号、短横线。建议使用业务系统主键或 SHA-256。
isUpdateboolean否默认 false。已存在时提交必须显式设为 true 才会更新,否则返回 409。
titlestring是标题,2–120 字符。
summarystring是简介/摘要,10–300 字符,显示在列表与分享卡片。
contentHtmlstring是富文本正文 HTML,支持标题、列表、引用、表格、代码、图片与链接;服务端会清洗不安全标签。最大 1MB。
coverImagestring否默认配图。支持 https://…、/uploads/… 或 /images/…。
authorstring否作者署名,最长 80 字符;不填则显示 API Key 所属账户名称。
publishedAtstring否发布时间,ISO 8601,例如 2026-11-17T10:00:00+08:00。不填则使用当前时间。
categoryIdinteger否分类 ID。和 categorySlug 二选一;都不填时使用“不分类”。
categorySlugstring否分类标识,如 industry-news、tech-docs、insights。
collectionIdinteger / null否归属合集 ID;传 null 表示不归入合集。
collectionOrderinteger否合集内默认排序值,0–9999,越小越靠前。
sourceNamestring否资讯来源名称。
sourceUrlstring否具体来源 URL,必须是 http(s)。
statusstring否published(默认)或 draft。更新时省略则保留原状态。
isFeaturedboolean否是否设为编辑精选,默认 false。

正文 HTML 会经过服务端白名单清洗,<script>、事件属性和 javascript: 协议不会保留。

05 / UPSERT

更新与幂等

hashId 全局唯一,同一账户重复提交时可实现幂等更新:

isUpdate: false新建

hashId 不存在 → 创建;hashId 已存在 → 409 HASH_EXISTS。

isUpdate: true更新

hashId 存在且属于当前账户 → 更新;不存在 → 404;属于其他账户 → 409。

更新时只传需要修改的字段也可以:省略的字段会保留原值;传 null 或空字符串可清空可选的配图、合集、来源等字段。标题、简介和正文在创建时必填。

推荐调用方式

首次发布传 isUpdate: false;后续每次内容变化都传 isUpdate: true。这样即使网络上重试,也不会产生重复文章。

06 / EXAMPLES

代码示例

首次创建

curl -X POST https://info.consensusai.tech/api/v1/articles \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hashId": "industry-2026-11-17-001",
    "isUpdate": false,
    "title": "固态电池中试线的工程化拐点",
    "summary": "从材料体系到制造良率,产业正在跨过第一道门槛。",
    "contentHtml": "<h2>从实验室到中试线</h2><p>正文内容……</p>",
    "coverImage": "https://example.com/cover.jpg",
    "author": "产业研究部",
    "publishedAt": "2026-11-17T10:00:00+08:00",
    "categoryId": 2,
    "collectionId": 4,
    "collectionOrder": 10,
    "sourceName": "公开资料整理",
    "sourceUrl": "https://example.com/source",
    "status": "published",
    "isFeatured": false
  }'

更新同一篇资讯

curl -X POST https://info.consensusai.tech/api/v1/articles \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hashId": "industry-2026-11-17-001",
    "isUpdate": true,
    "title": "固态电池中试线的工程化拐点(更新)",
    "summary": "补充了最新的中试线进展与良率数据。",
    "contentHtml": "<p>更新后的正文……</p>"
  }'

Python

import os, requests

r = requests.post(
    "https://info.consensusai.tech/api/v1/articles",
    headers={"Authorization": f"Bearer {os.environ['NEWS_API_KEY']}"},
    json={
        "hashId": "industry-2026-11-17-001",
        "isUpdate": True,
        "title": "固态电池中试线的工程化拐点",
        "summary": "从材料体系到制造良率,产业正在跨过第一道门槛。",
        "contentHtml": "<p>正文内容……</p>",
        "categorySlug": "industry-news"
    },
    timeout=30,
)
r.raise_for_status()
print(r.json()["data"]["url"])
07 / DISCOVERY

分类与合集

提交前可以读取平台当前可用的分类和合集,避免硬编码数据库 ID。

GET/api/v1/categories分类列表,含 id、name、slug
GET/api/v1/collections合集列表,含 id、name、文章数
GET/api/v1/articles/:hashId查询当前账户某条 hashId 的状态与内容

这些接口同样需要当前账户的有效 API Key。

08 / ERRORS

错误响应

所有错误都返回 JSON:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "提交内容未通过校验。",
    "fields": { "title": "标题必填" }
  }
}
HTTPcode含义
401UNAUTHORIZED / INVALID_API_KEY未提供、无效、禁用或所属账户停用。
409HASH_EXISTShashId 已存在,但 isUpdate 不为 true。
409HASH_OWNERSHIP_CONFLICT该 hashId 已属于其他账户,当前 Key 无权更新。
404ARTICLE_NOT_FOUNDisUpdate 为 true 但对应 hashId 不存在。
415UNSUPPORTED_MEDIA_TYPE未使用 application/json。
422VALIDATION_ERROR字段校验失败,见 fields。
500INTERNAL_ERROR服务器内部错误,可稍后重试。
READY TO CONNECT

从一条资讯开始。

创建 API Key,然后把你的内容系统接上。

创建 API Key