---
name: kaka-openapi
description: 当用户想生成小红书爆款图文（标题+正文+多页配图）、公众号/平台封面、知识卡片时使用——通过卡咔开放平台 API 完成创作、逐页出图与单页重生的全流程。
---

# 卡咔开放平台：AI 图文生成（Skill v2.2，2026-10-14）

通过卡咔开放平台 API，为用户生成三类内容：

| 场景 | 端点前缀 | 产物 |
|------|---------|------|
| 小红书爆款图文 | `/openapi/v1/viral/*` | 标题 + 正文 + 多页配图卡片（3~15 页，3:4） |
| 公众号/平台封面 | `/openapi/v1/covers/*` | 一次多规格封面（2.35:1 横版、3:4、9:16 等） |
| 知识卡片 | `/openapi/v1/cards/*` | 文本 → 润色 → 多页知识卡片（9:16/3:4/1:1） |

> **远程 MCP 接法（2026-10-01 新增，与下文 REST 等价）**：你的环境若支持远程 MCP（WorkBuddy / 豆包工作 / 千问等 AI 工作台），可直接连 `https://api.cardcrafter.cn/mcp`（Streamable HTTP），请求头带 `Authorization: Bearer $KAKA_API_KEY`，12 个工具（get_me / list_styles / generate_viral_outline / generate_viral_images / generate_cover / generate_card / get_record 等）与本文 REST 端点一一对应，出图轮询由 get_record 承担。

一篇图文 = 一条 record，三类场景共用 `GET /records/:record_id` 轮询。

## 前置条件

- **API Key**：需要环境变量 `KAKA_API_KEY`，值以 `kc-` 开头。每个请求通过 `Authorization: Bearer $KAKA_API_KEY` 传递（也可用 `X-API-Key` 头）。
- **Base URL**：默认 `https://api.cardcrafter.cn`，可用环境变量 `KAKA_BASE_URL` 覆盖。下文 curl 统一写作 `${KAKA_BASE_URL:-https://api.cardcrafter.cn}`。
- **计费**：与网页端同价——爆款图文大纲按次、封面/卡片/出图按张（调 `GET /me` 可查能量余额与价格相关配额）。消耗绑定账号的能量，生成记录在卡咔网页端可见（来源标记 `api`），生成失败自动退款。
- **编码红线（Windows 环境必读）**：含中文的请求体**严禁内联在 curl 命令里**——中文 Windows 控制台会把命令行参数按 GBK 转码后交给 curl.exe，服务端按 UTF-8 解码即成乱码，返回 422 `mojibake_detected` 拒收。正确做法：先把请求体 JSON 写成 UTF-8 文件（用你的文件写入工具或 heredoc），再 `curl --data-binary @文件` 发送。远程 MCP 通道不经过 shell 参数，无此问题。**下文所有含中文的 POST/PUT 示例均已按此写法给出，照抄即可。**

### ⚠️ 第一步（必做）：确认有可用的 API Key

调用任何卡咔接口前，先确认环境里有 `KAKA_API_KEY`（以 `kc-` 开头）。**没有、或任何接口返回 401，就停下来引导用户自助创建，不要瞎猜、不要反复重试。** 直接对用户说（可照抄）：

> 你还没配置卡咔 API Key，几步就能拿到：
> 1. 打开 **https://card.bingotech2022.com**，登录你的卡咔账号
> 2. 进入「API 接入」页面（用户中心侧栏 / 移动端「我的」页）
> 3. 点「**生成 API Key**」，复制 `kc-` 开头的 key（明文只显示这一次）
> 4. 回到这里设置环境变量：`export KAKA_API_KEY=kc-你复制的key`
>
> 配好后告诉我，我继续帮你生成。

拿到 key 再进行后续流程；key 消耗的是该用户自己账号的能量。

## 核心交互原则（必读）

### 1. 爆款图文默认走「分步模式」，别急着出图

1. `POST /viral/outlines`（**不带** `auto`）先生成大纲；
2. 把返回的**标题、正文、每页配图说明**用 markdown 排版展示给用户，征求意见；
3. 用户提修改意见时，**由你自己改好 pages JSON**，调 `PUT /viral/outlines/:record_id` 整组覆盖更新（不扣能量），再展示；
4. 用户明确确认满意后，才调 `POST /viral/images` 出图。

用户明确说"直接出"时才带 `auto: true`。**封面与卡片没有分步模式**——提交即出图。

### 2. 出图是异步的，靠轮询拿结果

提交出图（viral images / covers / cards）后，**每 15~30 秒**调一次 `GET /records/:record_id`，直到 `status` 进入终态：`completed` / `partial` / `error`。通常需要 2~5 分钟。结果用 markdown 图片列表呈现。

### 3. `partial` 时主动兜底

`status: partial` 表示部分页失败。明确告诉用户哪几页失败，并询问是否单页重生成：viral 用 `POST /viral/images/regenerate`，封面用 `POST /covers/regenerate`，卡片用 `POST /cards/regenerate`。重生成异步，继续轮询。

### 4. 挑场景、挑风格

- 用户说"写小红书" → viral；说"公众号封面/横版封面" → covers；说"把这些知识点做成卡片" → cards。
- 用户没指定风格就别传 `style` / `style_id` / `visual_style_preset_id`，走服务端默认；用户想挑时先 `GET /styles?scene=viral|cover|card` 列出风格让用户选。
- 封面必须知道规格：先 `GET /covers/platforms` 列出可用平台规格（如 `wechat_article_cover` 2.35:1 横版），让用户挑或按场景推荐。

---

## 接口速查

### GET /openapi/v1/me — 账户信息

```bash
curl -sS "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/me" \
  -H "Authorization: Bearer $KAKA_API_KEY"
```

### GET /openapi/v1/styles?scene=viral|cover|card — 可用风格

```bash
curl -sS "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/styles?scene=cover" \
  -H "Authorization: Bearer $KAKA_API_KEY"
```

### GET /openapi/v1/covers/platforms — 封面可用规格

```bash
curl -sS "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/covers/platforms" \
  -H "Authorization: Bearer $KAKA_API_KEY"
```

### 爆款图文：POST /viral/outlines — 生成大纲（同步）

同步接口，通常 30 秒~2 分钟，**curl 必须带 `--max-time 300`**。

```bash
# 请求体先落盘（UTF-8），严禁把中文内联进 curl 命令
cat > /tmp/kaka-outline.json <<'EOF'
{"topic": "三伏天养生茶推荐", "page_count": 6}
EOF
curl -sS --max-time 300 -X POST "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/viral/outlines" \
  -H "Authorization: Bearer $KAKA_API_KEY" -H "Content-Type: application/json" \
  --data-binary @/tmp/kaka-outline.json
```

请求字段：`topic`（必填）；`style`（可选，来自 /styles?scene=viral）；`page_count`（可选 3~15）；`image_urls`（可选参考图 1~4 张）；`auto`（可选，true = 大纲后立即出图）；`callback_url`（可选，auto 时出图完成回调）。

响应：`record_id`、`title`、`content`、`pages[]`（`index`/`type` cover·content/`content`）、`points_cost`、`status: draft`。auto=true 时额外返回 `task_id` / `pages_submitted` / `images_points_cost`，`status: generating_images`；出图提交失败时大纲照常返回并附 `images_error`。

### 爆款图文：PUT /viral/outlines/:record_id — 编辑大纲（不扣能量）

`pages` **整组覆盖**（1~15 页），`title` / `content` 可选。图片生成中返回 409。

```bash
cat > /tmp/kaka-pages.json <<'EOF'
{"pages":[{"index":0,"type":"cover","content":"改后的封面说明"}]}
EOF
curl -sS -X PUT "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/viral/outlines/rec_xxxx" \
  -H "Authorization: Bearer $KAKA_API_KEY" -H "Content-Type: application/json" \
  --data-binary @/tmp/kaka-pages.json
```

### 爆款图文：POST /viral/images — 整篇出图（异步）

请求：`record_id`（必填）；`image_urls`；`force`（已完成记录整篇重出时 true）；`callback_url`。
响应：`{"record_id":"...","task_id":"...","pages_submitted":6,"points_cost":120,"status":"generating_images"}`

### 封面：POST /covers — 多规格封面生成（异步）

```bash
cat > /tmp/kaka-cover.json <<'EOF'
{
  "title": "AI 绘画入门指南",
  "subtitle": "零基础 10 分钟上手",
  "platforms": ["wechat_article_cover", "xiaohongshu_cover"],
  "visual_style_preset_id": "可选",
  "style_type": "shock"
}
EOF
curl -sS -X POST "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/covers" \
  -H "Authorization: Bearer $KAKA_API_KEY" -H "Content-Type: application/json" \
  --data-binary @/tmp/kaka-cover.json
```

请求字段：`title`（必填）；`subtitle` / `content`（可选）；`platforms`（必填 1~5 个，来自 /covers/platforms）；`style_type`（可选：custom/shock/list/compare/pitfall/case）；`visual_style_preset_id`（可选，来自 /styles?scene=cover）；`custom_prompt`（可选）；`callback_url`。
响应：`{"record_id":"...","pages_submitted":2,"points_cost":40,"status":"generating_images"}`。计费 = 去重规格数 × 单张价。

### 卡片：POST /cards — 知识卡片生成（异步，一步到位）

```bash
cat > /tmp/kaka-card.json <<'EOF'
{"text": "Effort 与 Reward 是评价动作价值的一对维度……", "style_id": "从 /styles?scene=card 获取", "ratio": "9:16"}
EOF
curl -sS -X POST "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/cards" \
  -H "Authorization: Bearer $KAKA_API_KEY" -H "Content-Type: application/json" \
  --data-binary @/tmp/kaka-card.json
```

请求字段：`text`（必填，原文，服务端自动润色）；`style_id`（必填，来自 /styles?scene=card）；`platform`（可选，默认 xiaohongshu）；`ratio`（可选 9:16/3:4/1:1，默认 9:16）；`callback_url`。
响应：`{"record_id":"...","points_cost":15,"status":"generating_images"}`（按次计费，含润色）。

### 通用：GET /records/:record_id — 状态轮询

```bash
curl -sS "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/records/rec_xxxx" \
  -H "Authorization: Bearer $KAKA_API_KEY"
```

响应关键字段：`status`（draft | generating_outline | generating_images | completed | partial | error）、`scene`（viral/cover/card）、`title` / `content`、`pages[]`（`index`/`type`/`content`/`status` not_generated·generating·completed·failed/`image_url`）、`points_cost`（累计消耗）、`error_message`。图片 URL 为 OSS 持久链接。

### 单页重生成（异步）

```bash
# 爆款图文
curl -sS -X POST "${KAKA_BASE_URL:-https://api.cardcrafter.cn}/openapi/v1/viral/images/regenerate" \
  -H "Authorization: Bearer $KAKA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id": "rec_xxxx", "page_index": 2}'
# 封面 / 卡片同理，端点换为 /covers/regenerate、/cards/regenerate（可带 feedback 字段）
```

该页生成中返回 409；支持可选 `feedback`（封面/卡片）与 `callback_url`。`feedback` 含中文时同样先落盘再 `--data-binary @文件` 发送。

---

## Webhook 回调

提交出图时可传 `callback_url`，记录到达终态时 POST：

```jsonc
{
  "event": "record.finished",
  "record_id": "...",
  "status": "completed",
  "timestamp": 1783600000,
  "record": { /* 与 GET /records/:id 相同结构 */ }
}
```

请求头：`X-Kaka-Event: record.finished`；`X-Kaka-Signature: hex(HMAC-SHA256(rawBody, keyHash))`，其中 keyHash = 你的 API Key 明文的 SHA-256 十六进制小写（64 字符），用于验签。2xx 视为成功；失败重试 2 次（5s/15s）。回调尽力而为（服务重启会丢失），请以 `record_id + status` 幂等，并保留轮询兜底。

---

## 错误处理

非 2xx 统一返回 `{"error":{"code":"...","message":"..."}}`。按状态码处置：

| 状态码 | code | Agent 该怎么做 |
|---|---|---|
| 401 | `missing_key`/`invalid_key`/`key_disabled`/`user_disabled` | Key 缺失或无效。**引导用户自助创建**（见上方话术），不要反复重试 |
| 402 | `insufficient_energy` | 能量不足。调 `GET /me` 报 `energy_balance`，引导去卡咔网页端充值 |
| 403 | `forbidden` | 访问了他人资源，检查 record_id 是否属于当前 key 的账号 |
| 404 | `not_found` | 资源不存在，检查 record_id |
| 409 | `conflict` | 生成中/已完成。不是错误——继续轮询；整篇重出已完成记录用 `force: true`（仅 viral images） |
| 422 | `invalid_request` | 参数错误，按 message 修正请求体 |
| 422 | `mojibake_detected` | 请求体含乱码字符 U+FFFD——命令行内联中文被 GBK 转码所致。把 JSON 写成 UTF-8 文件后 `--data-binary @file` 重发，不要内联中文 |
| 429 | `quota_exceeded` | 日配额用尽（`GET /me` 可查），明天再试 |
| 429 | `rate_limited` | 提交过于频繁，等 2 秒重试 |
| 503 | `api_disabled` | 开放平台已关闭，告知用户联系管理员 |
| 504 | `timeout` | 大纲生成超时，任务仍在后台执行；响应体 `error.record_id` 即轮询用的记录 ID（`GET /records/:id`） |
| 5xx | `internal_error` | 服务端异常，等几秒重试一次；再失败如实报告用户 |

## 注意事项

- 爆款图文单篇 **3~15 页**（含封面）；PUT 编辑必须整组覆盖 1~15 页。
- 大纲接口同步、服务端超时上限 4 分钟——curl 请带 **`--max-time 300`**。
- 请勿并发对同一 record 提交出图（409 保护）。
- 生成内容的归属与合规责任由调用方承担，平台保留全部生成记录；涉及功效宣称、医疗等敏感品类时提醒用户自行把关文案合规。