跳到主内容
彤鑫 OPC AI 系统彤鑫 OPC
登录
返回首页
Developer Reference

API 文档

通过 PAT（个人访问令牌）以 REST 接入彤鑫OPC：拉对话、发消息、触发 AI、查用量。 所有端点都走 HTTPS，统一 JSON 编码，CORS 全开。需要把对话嵌入到博客？请见 /docs/embed。

起步：3 步集成

  1. 1. 登录后访问 /api-tokens 创建 PAT，复制 token 字符串。
  2. 2. 把 token 存为环境变量：export TOKEN=txopc_xxx
  3. 3. 调用任一接口（见下文）。

鉴权

—PAT 创建PAT(read)

登录后在 /settings/api-tokens 创建 PAT（个人访问令牌）。所有请求需在请求头携带 Authorization: Bearer <token>。

curl
Authorization: Bearer txopc_xxxxxxxxxxxx

对话 / Conversations

GET/api/public/v1/conversationsPAT(read)

列出当前 PAT 所属用户的对话，按更新时间倒序。支持 limit/offset。

curl
curl -H "Authorization: Bearer $TOKEN" \
  "https://txopc.ai/api/public/v1/conversations?limit=20"

消息 / Messages

GET/api/public/v1/messagesPAT(read)

拉取指定对话的消息列表（按时间正序）。

curl
curl -H "Authorization: Bearer $TOKEN" \
  "https://txopc.ai/api/public/v1/messages?conversation_id=<uuid>&limit=50"
POST/api/public/v1/messagesPAT(write)

创建一条消息。conversation_id 省略时自动新建对话。设 trigger_ai: true 时同步触发 AI 回复并返回 assistant 字段。

curl
curl -X POST "https://txopc.ai/api/public/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "总结一下我们昨天的对话",
    "trigger_ai": true,
    "model": "google/gemini-2.5-flash"
  }'

技能市场 / Skills

GET/api/public/v1/skills公开

公开技能市场列表，免授权。支持 q（搜索）、tag、sort=hot|new|top、limit、offset。

curl
curl "https://txopc.ai/api/public/v1/skills?sort=hot&limit=10"
GET/api/public/v1/skills/:slug公开

返回单个公开技能详情 + 最近 20 条评分摘要。

curl
curl "https://txopc.ai/api/public/v1/skills/code-review"

作者 / Profiles

GET/api/public/v1/profiles/:handle公开

按 handle 返回作者公开信息（含 followers / skills / installs / ratings 汇总 + 最近 20 条已发布技能）。handle 大小写不敏感。

curl
curl "https://txopc.ai/api/public/v1/profiles/alice"
GET/api/public/v1/profiles/:handle/skills公开

作者发布的公开技能（最近 50 条）。

curl
curl "https://txopc.ai/api/public/v1/profiles/alice/skills"
GET/api/public/v1/profiles/:handle/shares公开

作者公开分享对话（最近 30 条，含每条留言数）。

curl
curl "https://txopc.ai/api/public/v1/profiles/alice/shares"
GET/u/:userId/rss.xml公开

作者 RSS 订阅源：合并发布的技能 + 公开评论 + 公开留言（最多 30 条）。

curl
curl "https://txopc.ai/u/<userId>/rss.xml"

平台 / Platform

GET/api/public/v1/healthz公开

服务健康检查，不查数据库，适合外部监控。

curl
curl "https://txopc.ai/api/public/v1/healthz"
GET/api/public/v1/stats公开

全站公开聚合：作者数 / 公开技能 / 公开分享 / 留言数，以及 24h / 7d 增量；60s 边缘缓存。

curl
curl "https://txopc.ai/api/public/v1/stats"
GET/api/public/v1/trending公开

热门分享列表。?window=24h|7d|30d&limit=30，按 (留言×3 + 收藏×2 + 基础分) 排序。

curl
curl "https://txopc.ai/api/public/v1/trending?window=7d&limit=10"
GET/feed/trending.rss.xml公开

全站 7 日热门 RSS 2.0 订阅源（≤30 条），含 atom:link self。

curl
curl "https://txopc.ai/feed/trending.rss.xml"
GET/feed/latest.rss.xml公开

全站最新公开分享 RSS 2.0（≤30 条），按 updated_at 倒序。

curl
curl "https://txopc.ai/feed/latest.rss.xml"
GET/api/public/v1/feeds公开

发现端点：列出全站所有可订阅 RSS / sitemap / JSON 源。

curl
curl "https://txopc.ai/api/public/v1/feeds"
GET/api/public/v1/changelog公开

平台更新日志（feature/improvement/fix/security），?limit≤100。

curl
curl "https://txopc.ai/api/public/v1/changelog?limit=20"
GET/api/public/v1/changelog/:version公开

单条更新日志详情，version 形如 2026.05.22。

curl
curl "https://txopc.ai/api/public/v1/changelog/2026.05.22"
GET/feed/changelog.rss.xml公开

平台更新日志 RSS 2.0 订阅源。

curl
curl "https://txopc.ai/feed/changelog.rss.xml"
GET/feed/changelog.atom.xml公开

平台更新日志 Atom 1.0 订阅源（NetNewsWire 等客户端友好）。

curl
curl "https://txopc.ai/feed/changelog.atom.xml"
GET/api/public/v1/comments/recent公开

最近的公开技能评论（默认 20，最多 50），含作者与深链。

curl
curl "https://txopc.ai/api/public/v1/comments/recent?limit=20"
GET/api/public/v1/profiles/:handle/comments公开

作者在公开技能 / 公开分享下的最近评论合并流，按时间倒序（≤100）。

curl
curl "https://txopc.ai/api/public/v1/profiles/alice/comments?limit=30"

嵌入 / Embed

GET/share/:id/embed公开

轻量 iframe 嵌入页（noindex），无导航、无评论，仅消息流 + 返回原文按钮。详细见 /docs/embed。

curl
<iframe src="https://txopc.ai/share/<id>/embed" loading="lazy" style="width:100%;height:600px;border:0"></iframe>

分享 / Shares

GET/api/public/v1/shares公开

公开分享对话列表。?limit=24&sort=latest|commented&handle=<author>&cursor=<iso>。返回 items[] 与 nextCursor。

curl
curl "https://txopc.ai/api/public/v1/shares?sort=commented&limit=10"
GET/api/public/v1/shares/:id公开

返回单个公开分享对话的完整 JSON：标题、模型、tags、作者、留言数与全部消息（role + text）。仅在分享开启时可访问。

curl
curl "https://txopc.ai/api/public/v1/shares/<conversationId>"

动态封面 / OG

GET/og/skills/:slug公开

技能动态 OG 封面（SVG，1200×630）。可作为 <img> 或 og:image 直接使用。

curl
curl "https://txopc.ai/og/skills/code-review" -o cover.svg
GET/og/author/:userId公开

作者动态 OG 封面（SVG，1200×630）。含头像 / handle / 公开技能数 / 安装 / 关注者；s-maxage=600。

curl
curl "https://txopc.ai/og/author/<userId>" -o author.svg
GET/og/share/:conversationId公开

分享对话动态 OG 封面（SVG，1200×630）。

curl
curl "https://txopc.ai/og/share/<id>" -o share.svg

用量 / Usage

GET/api/public/v1/usagePAT(read)

返回最近 N 天（默认 30，最多 90）的用量统计：总额、按模型分布、按天趋势。

curl
curl -H "Authorization: Bearer $TOKEN" \
  "https://txopc.ai/api/public/v1/usage?days=30"

健康 & 暂停 / Health Snooze（公开脱敏）

GET/api/public/v1/healthz/score公开

当前平台健康分（0–100）+ tone（ok/warn/bad）+ 4 维度拆分（email/ai/cache/notif）。

curl
curl "https://txopc.ai/api/public/v1/healthz/score"
GET/api/public/v1/healthz/history?days=14公开

日度健康分序列（avg / min / max / samples），days 范围 7–90。

curl
curl "https://txopc.ai/api/public/v1/healthz/history?days=14"
GET/api/public/v1/healthz/snooze-stats公开

管理员告警暂停总数与占比（脱敏，无任何 PII）。60s 缓存。

curl
curl "https://txopc.ai/api/public/v1/healthz/snooze-stats"
GET/api/public/v1/healthz/snooze-stats.svg公开

自托管 SVG 徽章（不依赖 shields.io）：?lang=zh|en&theme=light|dark。

curl
<img src="https://txopc.ai/api/public/v1/healthz/snooze-stats.svg?lang=zh" alt="snooze" />
GET/api/public/v1/healthz/snooze-buckets公开

剩余暂停时长分桶（lt_1h/lt_6h/lt_24h/lt_7d/gte_7d/gte_30d），脱敏。

curl
curl "https://txopc.ai/api/public/v1/healthz/snooze-buckets"
GET/api/public/v1/healthz/snooze-bucket-shields.json公开

shields.io schema：长期暂停（≥30d）人数徽章。?lang=zh|en。

curl
https://img.shields.io/endpoint?url=https%3A%2F%2Ftxopc.ai%2Fapi%2Fpublic%2Fv1%2Fhealthz%2Fsnooze-bucket-shields.json
GET/api/public/v1/healthz/snooze-trend?days=30公开

近 N 天（7–90）snooze / snooze_expired / unsub 三类事件日度计数（脱敏）。

curl
curl "https://txopc.ai/api/public/v1/healthz/snooze-trend?days=30"

速率限制

所有 PAT 端点共享速率限制：
• 1 分钟内 60 次
• 1 小时内 600 次
• 24 小时内 5000 次
触发限制返回 429，附带 Retry-After 与 X-RateLimit-* 响应头。
实时余量见登录后的 /api-quota 页面。

错误码

统一错误响应：{ "error": "<code>", "detail?": "<msg>" }
常见 code：
• unauthorized — Token 缺失或失效，重新生成 PAT
• forbidden — 当前 PAT 缺少所需 scope（read / write）
• rate_limited — 触发速率限制
• not_found / conversation_not_found
• invalid_body — 请求体校验失败，detail 字段含 zod 错误
• ai_failed — AI 网关临时失败（消息已落库，可重试 trigger_ai）

在线调试 · Try it

直接在浏览器内发出请求。请求会以你当前浏览器会话发起；若端点需 PAT，请粘贴 token。

下一步

  • · 实时配额查看：/api-quota
  • · 管理 PAT：/api-tokens
  • · 用量分析：/usage
  • · OpenAPI 规范（机器可读）：/api/public/v1/openapi.json
  • · TypeScript SDK 雏形：packages/sdk-ts（仓库内，bun add @txopc/sdk 即用，覆盖 skills/conversations/messages/usage）
  • · 反馈或申请更高速率请到 /help