API 接入说明 V1.1：先看懂，再交给技术接入

小白版接入流程：只需要盯住 5 件事

Token 是接口钥匙，必须放在服务端

这一段给技术同事看。所有 API 请求都要带 Token，可以理解成“接口钥匙”。它只能放在你们自己的服务器里，不能放到网页、客户端安装包、公开文档或微信群截图里。

Authorization: Bearer yxe_live_xxxxxxxxxxxxx
Content-Type: application/json

文章发布接口 · POST /api/v1/articles/publish

POST https://yanxiaoer.openclawcn.com.cn/api/v1/articles/publish

这是技术真正要调用的接口。简单说：把一篇文章和一个账号分组交给颜小二，颜小二就按这组账号去创建发布任务。

字段说明：哪些必须填，哪些可选

V1.1 不接收调用方自传 callback_url，也不接收 scheduled_at。callback_url 统一在租户控制台配置。

cURL

curl -X POST "https://yanxiaoer.openclawcn.com.cn/api/v1/articles/publish" \
  -H "Authorization: Bearer yxe_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_article_id": "cms_20260508_0001",
    "group_code": "brand_main",
    "title": "AI 内容系统为什么需要自动发布层",
    "content_html": "<p>这是一篇由内容系统生成并推送到颜小二的文章。</p>",
    "cover_url": "https://cdn.example.com/covers/ai-publish.jpg",
    "summary": "让内容从生成走到真实发布。",
    "tags": ["AI", "自媒体", "自动发布"],
    "category": "科技",
    "publish_type": "publish"
  }'

JavaScript

const response = await fetch('https://yanxiaoer.openclawcn.com.cn/api/v1/articles/publish', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.YANXIAOER_API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_article_id: 'cms_20260508_0001',
    group_code: 'brand_main',
    title: 'AI 内容系统为什么需要自动发布层',
    content_html: '<p>这是一篇由内容系统生成并推送到颜小二的文章。</p>',
    publish_type: 'publish'
  })
});
const result = await response.json();

接口返回 accepted，表示“已经收下并开始排队”

提交成功不等于已经发到平台，而是颜小二已经收下文章并创建发布任务。真正发布成功或失败，会通过回调和看板继续查看。

{
  "code": 0,
  "message": "accepted",
  "data": {
    "job_id": "job_f4b6d7c2a9c0410eb6c2c4d6e2f6a001",
    "article_id": 1024,
    "external_article_id": "cms_20260508_0001",
    "created_tasks": 4
  }
}

同一租户下 external_article_id 唯一。重复提交不会重复创建任务：

{
  "code": 0,
  "message": "duplicate_article",
  "data": {
    "job_id": "job_f4b6d7c2a9c0410eb6c2c4d6e2f6a001",
    "external_article_id": "cms_20260508_0001",
    "created_tasks": 0
  }
}

回调就是：发布完以后通知你的系统

如果发布成功，回调里会带上文章链接；如果失败，会告诉你失败原因，比如账号需要重新登录、平台风控、电脑端 Agent 离线。不会看技术日志的人，也可以直接在看板里看。

POST {callback_url}
Content-Type: application/json
X-Callback-Source: media-publisher

{
  "job_id": "job_f4b6d7...",
  "external_article_id": "cms_20260508_0001",
  "platform": "toutiao",
  "account_code": "toutiao_main",
  "status": "success",
  "published_url": "https://www.toutiao.com/article/1234567890/",
  "error_code": null,
  "error_message": null,
  "status_note": null,
  "finished_at": "2026-05-08T12:30:00.000Z"
}

{
  "job_id": "job_f4b6d7...",
  "external_article_id": "cms_20260508_0001",
  "platform": "baijiahao",
  "account_code": "baijiahao_main",
  "status": "need_login",
  "published_url": null,
  "error_code": "ACCOUNT_NEED_LOGIN",
  "error_message": "账号登录失效，需要重新登录",
  "status_note": null,
  "finished_at": "2026-05-08T12:35:00.000Z"
}

失败时不要慌，先看是哪一类问题

运营不用看代码，也能查发布进度

颜小二不是把接口丢给你就结束。后台会把 API 调用、文章、任务、回调和 Agent 状态集中展示，运营能看懂，技术也能排查。