精品长文一键写作返回字段与 ret_code 说明（4 个接入点）
# 精品长文一键写作返回字段与 ret_code 说明（4 个接入点）
> 接口：精品长文一键写作（apiCode=3206）· 接入点：3206-1 / 3206-2 / 3206-3 / 3206-5
> 计费：计次收费，各接入点费率不同 · 请求方式：POST/GET · 返回格式：JSON（3206-3 生成中返回 HTTP 450，形态随 need_md 变化）
> 适用人群：接入调试中的开发者 · 阅读时间：约 7 分钟 · **最后实测核对：2026-09-15**
## 四个接入点共同的部分
| 项目 | 事实 |
|------|------|
| 接口地址前缀 | `https://route.showapi.com` |
| 鉴权 | URL query 参数 `appKey` |
| 外层封装 | `3206-1`、`3206-2`、`3206-5` 业务数据在 `showapi_res_body` 内；**`3206-3` 是透传模式，没有这一层** |
| 外层字段 | `showapi_res_code`、`showapi_res_error`、`showapi_res_id`、`showapi_fee_num` |
| 状态字段 | `task_status`：`preparing` / `writing` / `success` |
判断调用是否成功看 `ret_code`（在 `showapi_res_body` 里，`3206-3` 则在顶层）或外层的 `showapi_res_code`。`showapi_fee_num` 是本次调用计入的计费次数，实测 `3206-1` 返回 1、`3206-2` 返回 0。
## 3206-1 提交写作任务
**请求参数**
| 参数 | 类型 | 必须 | 说明 |
|------|------|------|------|
| `topic` | String | **是** | 写作要求，示例值「帮我写一篇关于DeepSeek的介绍」 |
| `reference_list` | String | 否 | 引用链接，JSON 数组字符串 |
| `lang` | String | 否 | 语言：`zh` 中文 / `en` 英文 |
| `file` | File | 否 | 引用文件 |
content-type 为 `multipart/form-data`。
**返回字段（`showapi_res_body` 内）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | String | 任务 id，示例 32 位十六进制串 |
| `topic` | String | 写作要求（原样回显） |
| `remark` | String | 接口调用描述 |
| `ret_code` | Number | 0 成功 / -1 失败 |
| `task_status` | String | `preparing` 准备执行 / `writing` 执行中 / `success` 执行成功 |
**实测返回（2026-09-15）**
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"topic": "写一篇介绍昆明气候特点的短文，300字左右",
"task_status": "preparing",
"remark": "文章正在生成中，请稍后！",
"task_id": "1ef05f9fa412444aa77c99fae4db1358",
"ret_code": 0
}
}
```
实测的 `remark` 是「文章正在生成中，请稍后！」，文档示例写的是「提交成功」。**判断成败请用 `ret_code`，不要拿 `remark` 做字符串匹配。**
## 3206-2 查询任务列表
**请求参数**
| 参数 | 类型 | 必须 | 说明 |
|------|------|------|------|
| `page` | String | 否 | 页码，示例值 1 |
content-type 为 `application/x-www-form-urlencoded`。文档说明该接入点可查询**近 30 天内**的任务列表。
**返回字段（`showapi_res_body` 内）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `allNum` | Number | 总数 |
| `allPages` | Number | 总页数 |
| `currentPage` | Number | 当前页数 |
| `maxResult` | Number | 当前页最大数（示例 20） |
| `contentlist` | Object[] | 任务列表 |
| `contentlist[].task_id` | String | 文章任务 id |
| `contentlist[].topic` | String | 文章要求（**会截断**，见下文） |
| `contentlist[].title` | String | 文章标题，生成中为空字符串 |
| `contentlist[].task_status` | String | `preparing` / `writing` / `success` |
| `contentlist[].content_length` | Number | 文章长度，生成中为 0 |
| `contentlist[].ct` | String | 提交时间，格式 `2026-09-15 12:08:31.284` |
| `contentlist[].remark` | String | 文章成功与否描述 |
| `remark` | String | 调用成功与否描述 |
| `ret_code` | Number | 0 成功 / -1 失败 |
**实测返回（2026-09-15）**
无任务时：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 0,
"showapi_res_body": {
"allNum": 0, "allPages": 0, "currentPage": 1, "maxResult": 20,
"contentlist": [], "remark": "查询成功", "ret_code": 0
}
}
```
有任务、但还在生成时：
```json
{
"showapi_res_body": {
"allNum": 1, "allPages": 1, "currentPage": 1, "maxResult": 20,
"contentlist": [{
"topic": "写一篇介绍昆明气候特点的短文，300字左......",
"task_status": "writing",
"remark": "文章正在生成中，请稍后！",
"ct": "2026-09-15 12:08:31.284",
"task_id": "1ef05f9fa412444aa77c99fae4db1358",
"title": "",
"content_length": 0
}],
"remark": "查询成功", "ret_code": 0
}
}
```
两个实测观察。**列表为空时 `allPages` 是 0**，文档示例里是 1，写分页循环时要对 0 做兜底。**`topic` 会截断为前 20 个字符加 6 个点**，列表页按这个长度排版，完整 `topic` 走 `3206-3`。
另外，请求超出范围的页码不会报错。2026-09-15 实测 `allPages=1` 时请求 `page=2`，返回 HTTP 200、`ret_code=0`、`currentPage=2`、`contentlist` 为空数组，`allPages` 仍为总数 1。分页循环用 `page <= allPages` 做终止条件即可，不必额外判断空数组。
## 3206-3 查询文章详情
**请求参数**
| 参数 | 类型 | 必须 | 说明 |
|------|------|------|------|
| `task_id` | String | **是** | 任务 id，具有唯一性 |
| `need_md` | String | 否 | 1 返回 Markdown 格式的正文 / 2 返回 JSON。实测该参数改变的是整个响应体形态，见下文 |
**返回字段（顶层，无 `showapi_res_body` 封装）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `title` | String | 文章标题 |
| `task_id` | String | 任务 id |
| `topic` | String | 写作要求 |
| `content` | String | 文章正文 |
| `task_status` | String | `preparing` / `writing` / `success` |
| `ret_code` | Number | 0 为成功，其它失败 |
| `remark` | String | 返回描述 |
| `keywords` | Object[] | 关键词列表 |
| `keywords[].keyword` | String | 关键词 |
| `keywords[].is_ai` | Boolean | 示例值为 `true` |
| `outline` | Object[] | 文章章节列表 |
| `outline[].name` | String | 章节名称 |
| `outline[].child_list` | String[] | 子章节列表 |
| `imgs` | String[] | 生成配图列表，未生成配图时为空数组 |
**`need_md` 决定响应体形态。** 这一点文档的参数说明里只写了「返回 Markdown 格式的正文」，实际影响的是整个响应体：
| `need_md` | 响应体 | 客户端解析 |
|------|------|------|
| `1` | 纯 Markdown 文本，以 `# 文章标题` 起头 | 读响应文本，不能 `json()` |
| `2` | JSON，正文在 `content` 字段 | `json()` 后取字段 |
| 不传 | 与传 `2` 相同 | 同上 |
2026-09-15 实测同一个 `task_id`：`need_md=1` 响应体 11780 字节，内容以 `# Exploring the ShowAPI Open API Marketplace: A Comprehensive Guide` 起头；`need_md=2` 与不传均返回 12788 字节的 JSON。GET 方式的响应形态一致。
**生成中的响应形态随 `need_md` 变化。** 2026-09-15 实测，文章未完成时该接入点返回 **HTTP 450**，响应体有两种：
`need_md=1` 时是一行纯文本：
```
文章正在生成中，请稍后！
```
`need_md=2` 或不传时是 JSON：
```json
{ "ret_code": -1,
"task_status": "writing",
"remark": "文章正在生成中，请稍后！" }
```
注意生成中的 `ret_code` 就是 **-1**。文档把它标注为「0 为成功，其它失败」，但生成中同样会返回 -1，所以判断顺序必须是「HTTP 状态码是不是 450 → `task_status`」，只看 `ret_code` 会把正常任务判成失败。
**成功返回的实测样本（`need_md=2`，2026-09-15）**
```json
{
"ret_code": 0,
"task_status": "success",
"task_id": "26d32f71742b40c2b7a91504e438c060",
"title": "Exploring the ShowAPI Open API Marketplace: A Comprehensive Guide",
"topic": "Write a brief introduction to the ShowAPI open API marketplace",
"remark": "文章生成完成",
"imgs": [],
"keywords": [
{ "is_ai": true, "keyword": "ShowAPI" },
{ "is_ai": true, "keyword": "开放接口" },
{ "is_ai": true, "keyword": "API市场" },
{ "is_ai": true, "keyword": "开发者平台" },
{ "is_ai": true, "keyword": "云服务" }
],
"outline": [
{ "name": "1. Introduction to ShowAPI and Its Significance",
"child_list": ["1.1 Understanding the Concept of an Open API Marketplace",
"1.2 The Evolution of API Markets in the Digital Era",
"1.3 ShowAPI's Position in the Cloud Service Ecosystem"] }
],
"content": "> ### 摘要 \n> ShowAPI is a leading aggregated open API marketplace, ……"
}
```
三处与文档示例不同的实测观察：
| 观察 | 实测结果 |
|------|------|
| `keywords[].keyword` 的语言 | 正文为英文时，关键词仍返回中文（`开放接口`、`API市场`、`开发者平台`、`云服务`），`is_ai` 全为 `true` |
| `outline` 的覆盖范围 | 该次返回 2 个章节，`content` 里实际出现 3 个 `##` 章节加一个 `## References` 参考文献小节；做目录以 `outline` 为准，但不要假设它覆盖正文全部标题 |
| `content` 开头的摘要小标题 | 固定为中文「摘要」，用 `> ### 摘要` 包裹，与正文语言无关 |
`content` 末尾会出现一个 `## References` 小节，列出编号的参考来源，来源包括提交时的 `reference_list` 和 `file`。不回填正文的话，这一段可以按 Markdown 结构裁掉。
## 3206-5 生成文案配图
**请求参数**
| 参数 | 类型 | 必须 | 说明 |
|------|------|------|------|
| `task_id` | String | **是** | 任务 id，具有唯一性 |
**返回字段（`showapi_res_body` 内）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `img` | String | 图片地址，文档注明「目前只有一张」 |
| `remark` | String | 示例值「成功」 |
| `ret_code` | Number | 文档未列出取值枚举，示例返回 0 |
`3206-5` 的读写超时按 OpenAPI 文档声明是 300 秒，比另外三个接入点的 60 秒长，调用时给足。
## 还有第五个接入点页面
`3206-4` 删除失败文章 的文档页在 https://www.showapi.com/apiGateway/view/3206/4 可以打开，接口地址是 `https://route.showapi.com/3206-4`，入参 `task_id`。它没有出现在接口页侧栏的接入点列表、计费规格表和 OpenAPI 文档里，这三处的接入点数量都是 4 个。2026-09-15 实测该地址可调用，返回 `{"remark":"删除成功","ret_code":0}`，`showapi_fee_num` 为 1。
## ret_code 取值汇总
| 接入点 | 文档给出的 `ret_code` 取值 |
|------|------|
| 3206-1 提交写作任务 | 0 成功 / -1 失败 |
| 3206-2 查询任务列表 | 0 成功 / -1 失败 |
| 3206-3 查询文章详情 | 0 为成功，其它失败 |
| 3206-4 删除失败文章 | 文档未给枚举，实测成功返回 0 |
| 3206-5 生成文案配图 | 文档未给枚举，示例返回 0 |
`3206-5` 与 `3206-4` 的文档没有列出完整取值，判断成败时建议用「等于 0 视为成功」的写法，同时记下原始 `remark` 便于排查。
## FAQ
**Q1：为什么 `3206-3` 的返回没有 `showapi_res_body`？**
该接入点是透传模式，直接返回服务商原始数据，业务字段都在最外层。想统一处理，可以在客户端封装里判断「有没有 `showapi_res_body`，没有就用响应体本身」。
**Q2：`showapi_res_code` 和 `ret_code` 有什么区别？**
`showapi_res_code` 是网关层面的状态码，`ret_code` 是接口业务层面的状态码。正常情况下两者都是 0。`3206-3` 生成中会返回 HTTP 450，此时 `need_md=2` 的响应体里没有 `showapi_res_code`，只有一个 `ret_code=-1`；`need_md=1` 时响应体是纯文本，两个字段都不存在。
**Q3：`keywords` 里的 `is_ai` 是什么意思？**
文档把它标为 Boolean，示例值全是 `true`，没有给出含义说明。按字段名理解是标记关键词的来源，实际用法以接口返回为准，不要基于它做业务分支。
**Q4：`imgs` 一直是空数组怎么办？**
`imgs` 是查询文章详情里携带的配图列表。要主动生成配图，调 `3206-5`，传 `task_id`，返回体里的 `img` 就是图片地址，文档注明目前只返回一张。
**Q5：`content_length` 和 `content` 的长度一致吗？**
不完全一致。`content_length` 出现在 `3206-2` 的列表里，`content` 出现在 `3206-3` 的详情里。2026-09-15 实测同一个任务，`3206-2` 返回的 `content_length` 是 11147，`3206-3` 返回的 `content` 长度是 11082，两者接近但存在差值。列表页用 `content_length` 做长度展示，需要精确值时以 `content` 的实际长度为准。
**Q6：`need_md` 不传会怎样？**
不传时返回 JSON，与传 `2` 的结果一致。只有在需要把整个响应体当作 Markdown 文档直接落地时才传 `1`。
## 下一步阅读
- 状态流转与轮询：[精品长文一键写作：任务写完了没有？看 task_status 三种状态](https://www.showapi.com/guides/longform-writing-task-status-3206)
- 端到端链路设计：[从一句主题到带配图长文的完整链路](https://www.showapi.com/guides/longform-writing-pipeline-3206)
- 计费口径：[精品长文一键写作计费口径：各接入点费率与资源包怎么算](https://www.showapi.com/guides/longform-writing-billing-3206)
- **本系列共 9 篇**：查看[精品长文一键写作指南总目录](https://www.showapi.com/guides/longform-writing-guides-3206)
