精品长文一键写作：从一句主题到带配图长文的完整链路
# 精品长文一键写作：从一句主题到带配图长文的完整链路
> 接口：精品长文一键写作（apiCode=3206）· 接入点：3206-1 / 3206-2 / 3206-3 / 3206-5
> 计费：计次收费（写作 300 厘/次、配图 260 厘/次、两个查询接入点 0 厘/次）· 请求方式：POST/GET · 返回格式：JSON
> 适用人群：内容系统开发、内容运营工具搭建者 · 阅读时间：约 9 分钟 · **最后实测核对：2026-09-15**
## 核心要点
- 整条链路是四步：提交任务 → 等状态 → 取正文 → 取配图，四个步骤对应四个接入点，没有回调，全靠轮询推进。
- 落库的关键是拿 `task_id` 当业务主键。有了它，任何一步断了都能从任意环节重入。
- `3206-5` 的配图文档注明「目前只有一张」，表结构按「一张主图」设计，不要预留多图数组。
## 链路为什么是四步
内容工具里最常见的需求是：运营给一句主题，系统产出一篇能直接发布的长文，最好还带一张配图。
精品长文一键写作把这件事拆成了四个可独立重入的步骤。这种拆法的好处是每一步都能单独重试：提交失败就重提，出稿失败就重新轮询，配图没生成就单独补一次，不用整条链路从头跑。
具体的顺序是这样：
```
运营提交主题
│
├─► 3206-1 提交写作任务 ──► 拿到 task_id（task_status=preparing）
│ │
│ ▼
│ 3206-2 查询任务列表（可选，用于总览）
│ 3206-3 查询文章详情（轮询，间隔 15~30s）
│ │
│ ├─ HTTP 450（生成中）──► 继续等
│ └─ task_status=success ──► 拿到 title/content/outline/keywords
│ │
│ ▼
│ 3206-5 生成文案配图 ──► img 图片地址
│ │
└──────────────────────────────────────────────────────────────┴─► 落库 / 发布
```
## 数据表怎么设计
四步链路里会产生三类数据：任务本身、文章内容、配图。用一个主表加两张从表最省事。
`task_id` 由接口生成，是全局唯一标识，直接当业务主键用。
```sql
-- 写作任务表
CREATE TABLE writing_task (
task_id VARCHAR(64) PRIMARY KEY, -- 接口返回的 task_id
topic VARCHAR(500) NOT NULL, -- 提交时的写作要求
lang VARCHAR(8) DEFAULT 'zh',
task_status VARCHAR(16) NOT NULL, -- preparing / writing / success
title VARCHAR(255) DEFAULT NULL, -- 出稿后回填
content_md MEDIUMTEXT DEFAULT NULL, -- need_md=1 的 Markdown 正文
content_len INT DEFAULT NULL, -- 3206-2 的 content_length
keywords JSON DEFAULT NULL, -- keywords[].keyword
outline JSON DEFAULT NULL, -- outline[].name / child_list
img_url VARCHAR(500) DEFAULT NULL, -- 3206-5 返回的 img
ret_code INT DEFAULT NULL,
remark VARCHAR(255) DEFAULT NULL,
ct DATETIME DEFAULT NULL, -- 3206-2 返回的提交时间
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
KEY idx_status (task_status),
KEY idx_ct (ct)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
`keywords` 和 `outline` 直接存 JSON。接口返回的结构本身就是嵌套的（`outline[].child_list` 是数组），拆成关系表再拼回去没有收益。
`3206-2` 返回的列表字段适合做一张轻量视图或缓存，不必单独建表：
| 列表字段 | 落库位置 | 说明 |
|------|------|------|
| `task_id` | `writing_task.task_id` | 主键 |
| `title` | `writing_task.title` | 生成中为空串 |
| `task_status` | `writing_task.task_status` | 与详情一致 |
| `content_length` | `writing_task.content_len` | 生成中为 0 |
| `ct` | `writing_task.ct` | 格式 `2026-09-15 12:08:31.284`，入库前截掉毫秒 |
| `topic` | 不入库 | 列表里被截断为前 20 字，入库要用提交时自己保存的原值 |
## 每一步怎么做
### 第一步：提交并立即落库
提交成功后先写一条 `task_status=preparing` 的记录，状态字段后续由轮询更新。这样提交和取稿解耦，即使服务重启，未完成的任务也能从库里扫出来继续轮询。
```python
import requests
def submit(topic, appkey, lang="zh"):
r = requests.post(
"https://route.showapi.com/3206-1",
params={"appKey": appkey},
data={"topic": topic, "lang": lang},
timeout=60,
)
r.raise_for_status()
body = r.json()["showapi_res_body"]
if body["ret_code"] != 0:
raise RuntimeError(body["remark"])
# 落库：topic 存自己传的原值，不要用 3206-2 里被截断的版本
save_task(task_id=body["task_id"], topic=topic, lang=lang,
task_status=body["task_status"])
return body["task_id"]
```
### 第二步：轮询到出稿
轮询用 `3206-3`，判断逻辑是「先看状态码，再看 `task_status`」。生成中返回 HTTP 450，此时 `ret_code` 是 **-1**——看起来像失败，其实是正常中间状态，只看 `ret_code` 会把还在生成的任务判成失败。完整记录见 [返回字段说明](https://www.showapi.com/guides/longform-writing-response-fields-3206)。
```python
import time
import requests
def fetch_article(task_id, appkey, interval=20, max_wait=900):
base = "https://route.showapi.com"
deadline = time.time() + max_wait
while time.time() < deadline:
time.sleep(interval)
r = requests.post(f"{base}/3206-3", params={"appKey": appkey},
data={"task_id": task_id, "need_md": "2"}, timeout=60)
if r.status_code == 450:
continue # 生成中，响应体是纯文本
r.raise_for_status()
d = r.json()
if d.get("task_status") == "success":
update_task(task_id, task_status="success", title=d.get("title"),
content_md=d.get("content"),
keywords=d.get("keywords"), outline=d.get("outline"))
return d
update_task(task_id, task_status=d.get("task_status", "writing"))
raise TimeoutError(f"{task_id} 超时未完成")
```
`need_md` 传 `2` 拿到 JSON，正文在 `content` 字段里；传 `1` 时响应体直接就是 Markdown 原文，`json()` 会失败。正文里带 `>` 引用块（摘要）和 `##` / `###` 章节标题，前端用 Markdown 渲染器直接展出即可。`content` 末尾还有一段 `## References` 参考文献列表，来源包括提交时的 `reference_list` 和 `file`，发布前按 Markdown 结构裁掉。
### 第三步：按需生成配图
配图不是自动出来的。正文里 `imgs` 在没有生成配图时是空数组，要单独调 `3206-5`：
```python
def fetch_image(task_id, appkey):
r = requests.post("https://route.showapi.com/3206-5",
params={"appKey": appkey},
data={"task_id": task_id},
timeout=300) # OpenAPI 声明该接入点读写超时 300s
r.raise_for_status()
body = r.json()["showapi_res_body"]
if body.get("ret_code") == 0 and body.get("img"):
update_task(task_id, img_url=body["img"])
return body.get("img")
```
文档对 `img` 字段的说明是「图片 目前只有一张」。表里留一个 `img_url` 字段就够，不需要多图结构。返回的图片地址来自接口的临时存储，落库时建议同时把图片转存到自己的对象存储，避免临时地址失效。
配图这一步可以按需触发：不是每篇内容都需要配图，把它做成一个独立按钮或队列消费者，比塞进主流程更省费用。
### 第四步：发布
到这一步你手上是四份数据：`title`、`content`（Markdown）、`keywords`、`outline`。摘要不用另外取，它在 `content` 开头的引用块里。
按你的发布目标做转换就行：CMS 直接吃 Markdown；要 HTML 就过一遍渲染器；要拆成多页，用 `outline[].name` 做页面标题、`child_list` 做小节锚点。
## 计费与调用方式
一次完整产出的调用次数是「1 次提交 + N 次轮询详情 + 1 次配图」。轮询不额外花钱（`3206-3` 为 0 厘/次），所以链路成本基本等于 300 厘（写作）+ 260 厘（配图）。调用成功才计费，失败不扣费。
接口并发量为 2 次/秒，多篇并行时记得节流。档位与费率明细见 https://www.showapi.com/apiGateway/view/3206 的「产品价格」标签。
## FAQ
**Q1：可以不落库，直接在内存里等吗？**
短流程可以。但长文生成按分钟计，把 `task_id` 落库能在服务重启或请求超时后继续接管，成本只是一张表。
**Q2：`outline` 和 `content` 里的标题会重复吗？**
会，而且覆盖范围也不完全相同。`outline` 是章节列表，`content` 里同一层级用 `##` / `###` 重复出现，做导航时用 `outline`。2026-09-15 实测的一次返回中，`outline` 列出 2 个章节，而 `content` 里出现了 3 个 `##` 章节加一个 `## References` 小节，`outline` 没有覆盖正文的全部标题。
**Q3：摘要怎么单独取出来？**
接口没有单独的摘要字段，摘要在 `content` 开头的引用块里，格式是 `> ### 摘要` 后面跟一段 `>` 引用的正文。这个「摘要」小标题固定为中文，与成稿语言无关。按 Markdown 结构解析第一段引用块即可。
**Q4：`content` 末尾的 References 是什么？**
是接口附在正文末尾的参考来源列表，格式为编号 + Markdown 链接，来源包括提交时的 `reference_list` 和 `file`。不需要对外展示时，按 Markdown 结构裁掉这一段。
**Q5：配图能改成多张吗？**
当前文档说明 `img` 只返回一张。需要多张就在调用侧对同一篇内容做多次不同提示的生成，接口本身没有数量参数。
**Q6：整个链路最慢的是哪一步？**
第二步轮询。2026-09-15 实测两个任务，一个约 7 分钟出稿，另一个提交后 87 分钟仍未出稿。把用户等待体验设计成「提交后离开页面、完成再通知」，比让用户盯着加载动画更合适。
## 下一步阅读
- 批量场景下的调度：[把批量写作任务排成队列的几种做法](https://www.showapi.com/guides/longform-writing-batch-queue-3206)
- 引用链接与引用文件：[reference_list、file、lang 三个参数怎么传](https://www.showapi.com/guides/longform-writing-reference-params-3206)
- 成本口径：[精品长文一键写作计费口径：各接入点费率与资源包怎么算](https://www.showapi.com/guides/longform-writing-billing-3206)
- **本系列共 9 篇**：查看[精品长文一键写作指南总目录](https://www.showapi.com/guides/longform-writing-guides-3206)
