如何接入颜小二自媒体发布 API（含完整代码示例）

如果你正在带 MCN 矩阵或者公司内部的多账号自媒体团队，发布动作正在被一份 Excel 和七八个浏览器标签拖着走，那就是接 API 的时候了。这篇文章给出一份能直接抄走的接入指南：5 个步骤、两段完整代码、一张错误码对照表，半天内就能跑通从"调 API"到"收回调"的完整闭环。

适用人群

• MCN 矩阵运营的技术中台同学，想把"复制粘贴 6 个平台"标准化成一次 HTTP 调用
• 企业自媒体团队的工程师，需要把内部 CMS 的发布按钮接到外部多平台
• AIGC 内容流水线的开发者，需要在 Agent 末端补一个稳定的执行出口
• 自建发布 RPA 已经维护不下去、希望迁到中台的团队

颜小二 API 接入是什么

颜小二自媒体发布 API 平台是一个多租户内容分发执行中台。"接入颜小二 API"指的是在你的业务系统里，通过 HMAC 签名调用统一文章接收 API（一个端点），把一篇文章的标题、正文、group_code、external_id 等字段提交进来，由颜小二把任务路由到对应账号、再把结构化结果通过 callback_url 推回给你。

> 一句话：业务侧只面对一个端点，多平台、多账号的复杂度由颜小二在底层处理。

前置条件

接入前需要准备好以下 4 项：

1. 租户凭证：API Key ID 与 Secret（在 [/contact.html#form](/contact.html#form) 申请） 2. callback_url：一个 HTTPS 公网可达的回调地址，用来接收 success / failed / login_expired 3. 账号分组规划：用业务维度命名 group_code，例如 brand_a_default、zhihu_only_kol_v1 4. 本地 Agent：需要登录的平台账号，登录态本地保存（cookie 不上云）

5 步完成接入

第 1 步：注册租户、生成 API Token

申请通过后你会拿到 YXE_API_KEY 和 YXE_API_SECRET。一个站长 = 一个租户，租户之间数据完全隔离，互不可见。Secret 只展示一次，建议立即写入你的密钥管理服务（如 Vault、KMS、AWS Secrets Manager）。

第 2 步：本地启动 Agent，完成账号登录

每个需要发布的账号，在本地 Agent 上扫码或密码登录一次。登录态保存在本地文件系统加密存储，颜小二云端只持有"哪个账号属于哪个 group_code"的元数据，不持有 cookie 本身。

第 3 步：实现 HMAC-SHA256 请求签名

颜小二的鉴权采用规范字符串 + HMAC-SHA256 签名。规范字符串构成：

`` METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA256(BODY) ``

下面是 Python 版本的最小可行实现：

```python import json, time, uuid, hashlib, hmac, requests

API_HOST = "https://api.yanxiaoer.example.com" API_KEY = "yxe_xxxxxxxxxxxxxxxx" API_SEC = "your_secret_only_once"

def post_article(payload: dict): path = "/api/v1/articles/publish" body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode() ts = str(int(time.time())) nonce = uuid.uuid4().hex body_hash = hashlib.sha256(body).hexdigest() canonical = f"POST\n{path}\n{ts}\n{nonce}\n{body_hash}" sig = hmac.new(API_SEC.encode(), canonical.encode(), hashlib.sha256).hexdigest() headers = { "Content-Type": "application/json", "X-YXE-Key": API_KEY, "X-YXE-Timestamp": ts, "X-YXE-Nonce": nonce, "X-YXE-Signature": sig, } return requests.post(API_HOST + path, data=body, headers=headers, timeout=30).json() ```

Node.js 版本的核心也是 5 行：

``javascript const crypto = require("crypto"); function sign(secret, method, path, body) { const ts = Math.floor(Date.now() / 1000).toString(); const nonce = crypto.randomUUID().replace(/-/g, ""); const bodyHash = crypto.createHash("sha256").update(body).digest("hex"); const canonical = [method, path, ts, nonce, bodyHash].join("\n"); const sig = crypto.createHmac("sha256", secret).update(canonical).digest("hex"); return { ts, nonce, sig }; } ``

第 4 步：调用统一文章接收 API

签名搞定后，把文章打包成下面这种结构提交：

``json { "external_id": "cms_article_2026_001", "group_code": "brand_a_default", "title": "深度解读：AI 时代企业内容矩阵的 3 个变化", "content_html": "<p>正文 HTML</p>", "cover_url": "https://yourcdn.com/cover.jpg", "summary": "一句话摘要", "tags": ["AI", "内容运营"], "category": "科技", "target_platforms": ["toutiao", "wechat_mp", "baijiahao", "zhihu"] } ``

external_id 是关键：颜小二以"租户 + external_id"为幂等主键，重复提交不会重复发布，对断网重试场景非常友好。

第 5 步：在 callback_url 接收结构化结果

callback 体里至少包含：external_id、platform、status（success / failed / login_expired）、platform_url、error_msg、retryable。建议你的接收端做三件事：

1. 用 X-YXE-Signature 头校验签名（防伪造） 2. 用 external_id + platform 作为业务侧主键入库（防重复） 3. 遇到 login_expired 时触发该账号的重登流程，而不是把整个矩阵暂停

更完整的字段定义见 [API 文档](/docs.html)。

错误排查清单

| 现象 | 可能原因 | 处理方式 | |---|---|---| | 401 invalid_signature | 签名串顺序错 / Secret 写错 | 比对 canonical 字符串五段是否完整 | | 401 timestamp_skew | 服务器时间偏离 ≥5 分钟 | 用 NTP 同步或改用 UTC 秒级时间戳 | | 409 duplicate_external_id | 同 external_id 已存在 | 业务侧重新生成稳定唯一 ID | | 422 group_code_not_found | 分组未创建 | 在控制台或调用分组接口先建 group | | callback 不到 | 防火墙 / HTTPS 证书无效 | 用 curl 从公网测一次可达性 | | 部分平台 login_expired | 本地账号 cookie 失效 | 触发该账号本地重登，其他账号不受影响 |

常见问题（FAQ）

Q：颜小二 API 接入安全吗？ 登录态本地保存，云端不存任何账号 cookie；HMAC-SHA256 签名 + timestamp + nonce 防重放；多租户数据物理隔离。具体看 [产品功能](/product.html)。

Q：颜小二 API 接入怎么选起点？ 推荐"1 租户 1 group_code 1 账号 1 篇文章"先把链路跑通，再扩到多账号、多平台。

Q：颜小二 API 接入推荐什么环境？ 建议生产环境与沙箱环境用两套 group_code 与两套 callback_url，避免测试任务串入正式账号。

Q：颜小二 API 接入价格怎么算？ 按租户 + 账号数 + 调用量分档，详见 [价格说明](/pricing.html) 或申请试用沟通。

Q：颜小二 API 接入 V1 版有哪些平台？ 当前 V1 完整支持头条号、微信公众号；百家号、知乎在 V1.1 规划中。

下一步

• 申请 Key：[免费申请接入](/contact.html#form)
• 文档参考：[API 文档](/docs.html)
• 落地页：[自媒体发布 API](/lp/zimedia-publish-api.html)