§01
鉴权
Bearer
curl -s https://claudebaby.cn/v1/social/reddit/posts \
-H "Authorization: Bearer $CB_KEY"也接受 X-API-Key。Key 在控制台签发，明文只展示一次；轮换时旧 Key 可设宽限期，避免换 Key 打断线上任务。
§02
数据面
MCP 与 REST 是同一份工具的两个门面，挂哪个都不用学第二套 schema。
| 项 | 值 |
|---|---|
| REST 路径 | https://claudebaby.cn/v1/{domain}/{platform}/{endpoint} |
| MCP（Streamable HTTP） | https://claudebaby.cn/mcp/{platform} |
| MCP（SSE） | https://claudebaby.cn/sse/{platform} |
| 请求关联 | 每个响应都带 X-Request-Id |
| envelope | MCP 的 structuredContent 与 REST 响应体逐字节一致 |
§03
账户自查
| 接口 | 返回 |
|---|---|
| GET /api/me | 账号 · 套餐 · 本周期额度 · 余额 · 水位 |
| GET /api/usage?groupBy=platform|day | 调用次数 · 积分 · 成功率 / 失败率 |
同样用 API Key 鉴权。余额、额度、失败率对客户完全透明 —— 这是产品承诺，不是「看情况」。
§04
错误码
| code | HTTP | 建议 | message |
|---|---|---|---|
| invalid_request | 400 | 不可重试 | The request parameters are invalid. |
| unauthorized | 401 | 不可重试 | Missing or invalid API key. |
| insufficient_balance | 402 | 不可重试 | Account balance is insufficient for this request. |
| not_found | 404 | 不可重试 | The requested resource does not exist. |
| rate_limited | 429 | 可重试 | Rate limit exceeded for this plan, please retry later. |
| job_not_ready | 409 | 可重试 | The job is still running. |
| upstream_unavailable | 503 | 可重试 | The data source is temporarily unavailable. |
| upstream_timeout | 504 | 可重试 | The data source did not respond in time. |
| capacity_exceeded | 503 | 不可重试 | Service capacity is saturated, please retry later. |
| internal_error | 500 | 可重试 | An internal error occurred. |
错误体固定为 {"error": {"code", "message", "retryable", "details"}}；限流与上游故障会带 Retry-After。