CHAINPEAKRESEARCH · PUBLISHING HANDBOOK

博客发布手册：API 对接与内容规范

给营销团队：如何通过 API 向 www.chainpeak.io 发布 Research 文章，以及标题、结构、图表和配色必须遵守的规范。发布后约 10 秒自动上线。

01 · QUICK START接入信息

Base URL	`https://www.chainpeak.io/api/blog`
认证方式	每个请求带请求头 `Authorization: Bearer <TOKEN>`
TOKEN	向管理员领取（不在本页出现；泄露可随时轮换）
返回格式	JSON；发布成功返回文章的正式 URL

先用 GET /health（免认证）确认服务在线，再用你的 TOKEN 调 GET /posts 验证密钥有效。

02 · ENDPOINTS端点一览

方法	路径	说明
GET	`/health`	健康检查，免认证
GET	`/posts`	已发布文章列表（slug、标题、日期、URL）
GET	`/posts/<slug>`	读取单篇的元数据与 Markdown 正文
POST	`/posts`	新建文章；slug 相同即覆盖更新。默认自动构建上线
DELETE	`/posts/<slug>`	删除文章，连带封面与该文所有图表，自动重建
POST	`/publish`	只重新构建发布（配合草稿模式 `publish:false` 使用）

03 · FIELDSPOST /posts 字段

字段	必填	规则
`title`	必填	55–70 个英文字符，包含目标关键词
`description`	必填	140–160 个英文字符，SEO 摘要，直接说结论
`body`	必填	正文 Markdown，结构见第 05 节
`slug`	建议	URL 路径，小写字母、数字、连字符；不填由标题自动生成
`tags`	建议	数组，如 `["Vietnam", "User Growth"]`；第一个会印在自动封面上
`keywords`	建议	逗号分隔的 SEO 关键词串，5–8 个词组
`faq`	建议	`[{"q":"…","a":"…"}]` 3–5 条。生成 FAQ 结构化数据，是 AI 搜索（GEO）抓取的重点，每篇都要写
`date`	可选	`YYYY-MM-DD`，默认当天
`author`	可选	默认 `ChainPeak Research`
`images`	可选	`[{"filename":"<slug>-1.svg","content_base64":"…"}]`，单张 ≤ 2MB，仅 svg / png / jpg / webp
`cover_svg`	可选	自定义封面 SVG 源码；不传则自动生成品牌封面；传 `"cover":"none"` 表示不要封面
`publish`	可选	默认 `true` 直接上线；`false` 存为草稿，之后调 `/publish` 上线

04 · EXAMPLE最小可用示例

curl -X POST "https://www.chainpeak.io/api/blog/posts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vietnam Crypto Airdrop Guide 2026: Channels, Costs, Pitfalls",
    "description": "How Web3 teams run airdrops in Vietnam in 2026: Zalo and Telegram channels, KOC seeding costs, anti-sybil filtering, and a launch checklist.",
    "slug": "vietnam-airdrop-guide-2026",
    "tags": ["Vietnam", "User Growth"],
    "keywords": "vietnam crypto airdrop, vietnam web3 marketing, KOC seeding vietnam",
    "faq": [{"q": "How much does a Vietnam airdrop cost?", "a": "Typical budgets run $5,000-20,000 ..."}],
    "body": "Opening paragraph with the conclusion...\n\n## Key Takeaways\n\n- Point one\n\n## First section\n\n![Chart alt text](/assets/img/figures/vietnam-airdrop-guide-2026-1.svg)\n"
  }'
# 成功返回：{"ok": true, "url": "https://www.chainpeak.io/blog/vietnam-airdrop-guide-2026/", "published": true, ...}

05 · CONTENT文章结构规范

全站是英文站，正文用英文写，语气与已发布的 14 篇文章一致（先结论、给数字、不写空话）。固定结构：

开头 2–3 段直接给结论——不写"随着区块链的发展"式导语
## Key Takeaways——5 条要点列表
若干 ## 小节，数据尽量用 Markdown 表格呈现
FAQ 写在 faq 字段里（不要写进正文），3–5 条

站内链接用相对路径：/regions/vietnam/、/services/kol-marketing/
外部引用加 nofollow：<a href="https://…" rel="nofollow"><strong>来源名</strong></a>
标题、摘要、关键词字数按第 03 节执行，这直接决定谷歌收录质量

06 · FIGURES图表 SVG 规范

文件名必须是 <slug>-1.svg、<slug>-2.svg…（删除文章时才能连带清理）
viewBox="0 0 1200 400"，高度可在 300–600 之间；不要加背景矩形——页面底色是 #060608，透明底直接融入
文字颜色：标题 #f2f4f8 粗体 ≥30px；轴标注 #9aa3b5 ≥24px；字体统一 Arial, Helvetica, sans-serif
不引用任何外部资源（外链字体、图片、脚本都会被浏览器拦截）
正文引用写法：![描述图表内容的 alt 文字](/assets/img/figures/<slug>-1.svg)，alt 必须写实际内容，利于 SEO 和无障碍

07 · PALETTE品牌配色

图表数据系列按下面顺序取色；正向/增长类数据优先用绿。

#0048FF

主品牌蓝 · 第 1 数据系列

#7A5CFF

蓝紫 · 第 2 系列

#B36BF7

亮紫 · 第 3 系列

#22D3EE

青 · 第 4 系列

#EC4899

粉 · 对比强调

#F5B94A

金 · 警示/费用类

#34D399

绿 · 正向/增长数据

#4D8CFF

亮蓝 · 辅助/连线

92° 渐变

#0048FF → #7A5CFF → #B36BF7 · 仅装饰线条

#060608

页面底色 · 图内勿用作填充

#F2F4F8

图表标题文字

#9AA3B5

轴标注/次要文字

公链专用色（画到对应链时使用）：SOL #9945FF · BNB #F0B90B · TON #0098EA · SUI #6FBCF0

08 · SELF-CHECK开工前自检

把密钥存进环境变量后，先跑这两条命令确认环境没问题，再开始发文章。

# 1. 检查密钥格式：应输出 长度: 48 / 格式正确: True
python3 -c 'import os,re; v=os.getenv("CHAINPEAK_BLOG_TOKEN",""); print("长度:",len(v)); print("格式正确:",bool(re.fullmatch(r"[0-9a-f]{48}",v)))'

# 2. 实际调用一次：应返回 {"ok": true, "count": N, "posts": [...]}
curl -s -H "Authorization: Bearer $CHAINPEAK_BLOG_TOKEN" https://www.chainpeak.io/api/blog/posts

密钥长度不是 48？说明变量被污染了。最常见的是 ~/.zshrc 里写了多行 export 导致重复拼接（长度会是 48 的整数倍）。修复：grep -n CHAINPEAK_BLOG_TOKEN ~/.zshrc 删掉多余的行，只保留一行，然后开一个新终端窗口重新自检。

密钥认证失败时，API 的返回体里会有 hint 字段直接说明原因（长度不对、漏写 Bearer、大小写错误等），照着提示改即可。

09 · ERRORS常见返回与排查

状态码	含义与处理
`401`	TOKEN 缺失或错误——检查 `Authorization: Bearer` 头
`400`	字段不合规——返回体的 `error` 会写明是哪个字段（slug 非法、图片超 2MB、base64 无效等）
`404`	slug 不存在（读取/删除时）
`500`	构建失败——内容已保存，把返回体里的 `build` 信息发给管理员

发布成功后打开返回的 URL 检查一遍：排版、图表显示、内链可点。slug 一旦被谷歌收录就不要再改；要改内容就用同一个 slug 重新 POST 覆盖。