快速开始
创建 API Key
登录编辑后台,打开「API Key」,创建一个属于当前账户的 Key。完整 Key 只显示一次。
查询分类
调用 GET /api/v1/categories 获取分类 ID 和 slug;如需归入合集,再查询 collections。
提交资讯
向 POST /api/v1/articles 发送 JSON。首次创建使用 isUpdate: false。
每个编辑/管理员账户管理自己的 Key。账户停用或 Key 被禁用后,使用该 Key 的请求会立即返回 401。
自动化集成可以直接读取 OpenAPI 3.1 规范,导入 Apifox、Postman 或代码生成器。
认证
所有 /api/v1/* 接口都需要 API Key。推荐放在 Authorization 请求头:
Authorization: Bearer cyk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx也兼容 X-API-Key 请求头。请始终在服务端保存 Key,不要放进浏览器前端代码、URL 参数或公开仓库。
https://info.consensusai.tech/api/v1/articles提交资讯
请求体为 JSON,Content-Type: application/json。成功创建返回 201,更新返回 200,响应中的 data.url 是前台可访问地址。
{
"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"
}
}字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
hashId | string | 是 | 资讯唯一标识,1–128 位字母、数字、点、下划线、冒号、短横线。建议使用业务系统主键或 SHA-256。 |
isUpdate | boolean | 否 | 默认 false。已存在时提交必须显式设为 true 才会更新,否则返回 409。 |
title | string | 是 | 标题,2–120 字符。 |
summary | string | 是 | 简介/摘要,10–300 字符,显示在列表与分享卡片。 |
contentHtml | string | 是 | 富文本正文 HTML,支持标题、列表、引用、表格、代码、图片与链接;服务端会清洗不安全标签。最大 1MB。 |
coverImage | string | 否 | 默认配图。支持 https://…、/uploads/… 或 /images/…。 |
author | string | 否 | 作者署名,最长 80 字符;不填则显示 API Key 所属账户名称。 |
publishedAt | string | 否 | 发布时间,ISO 8601,例如 2026-11-17T10:00:00+08:00。不填则使用当前时间。 |
categoryId | integer | 否 | 分类 ID。和 categorySlug 二选一;都不填时使用“不分类”。 |
categorySlug | string | 否 | 分类标识,如 industry-news、tech-docs、insights。 |
collectionId | integer / null | 否 | 归属合集 ID;传 null 表示不归入合集。 |
collectionOrder | integer | 否 | 合集内默认排序值,0–9999,越小越靠前。 |
sourceName | string | 否 | 资讯来源名称。 |
sourceUrl | string | 否 | 具体来源 URL,必须是 http(s)。 |
status | string | 否 | published(默认)或 draft。更新时省略则保留原状态。 |
isFeatured | boolean | 否 | 是否设为编辑精选,默认 false。 |
正文 HTML 会经过服务端白名单清洗,<script>、事件属性和 javascript: 协议不会保留。
更新与幂等
hashId 全局唯一,同一账户重复提交时可实现幂等更新:
hashId 不存在 → 创建;hashId 已存在 → 409 HASH_EXISTS。
hashId 存在且属于当前账户 → 更新;不存在 → 404;属于其他账户 → 409。
更新时只传需要修改的字段也可以:省略的字段会保留原值;传 null 或空字符串可清空可选的配图、合集、来源等字段。标题、简介和正文在创建时必填。
首次发布传 isUpdate: false;后续每次内容变化都传 isUpdate: true。这样即使网络上重试,也不会产生重复文章。
代码示例
首次创建
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"])分类与合集
提交前可以读取平台当前可用的分类和合集,避免硬编码数据库 ID。
/api/v1/categories分类列表,含 id、name、slug/api/v1/collections合集列表,含 id、name、文章数/api/v1/articles/:hashId查询当前账户某条 hashId 的状态与内容这些接口同样需要当前账户的有效 API Key。
错误响应
所有错误都返回 JSON:
{
"ok": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "提交内容未通过校验。",
"fields": { "title": "标题必填" }
}
}| HTTP | code | 含义 |
|---|---|---|
| 401 | UNAUTHORIZED / INVALID_API_KEY | 未提供、无效、禁用或所属账户停用。 |
| 409 | HASH_EXISTS | hashId 已存在,但 isUpdate 不为 true。 |
| 409 | HASH_OWNERSHIP_CONFLICT | 该 hashId 已属于其他账户,当前 Key 无权更新。 |
| 404 | ARTICLE_NOT_FOUND | isUpdate 为 true 但对应 hashId 不存在。 |
| 415 | UNSUPPORTED_MEDIA_TYPE | 未使用 application/json。 |
| 422 | VALIDATION_ERROR | 字段校验失败,见 fields。 |
| 500 | INTERNAL_ERROR | 服务器内部错误,可稍后重试。 |
从一条资讯开始。
创建 API Key,然后把你的内容系统接上。