精品长文一键写作：reference_list、file、lang 三个参数怎么传
# 精品长文一键写作：reference_list、file、lang 三个参数怎么传
> 接口：精品长文一键写作（apiCode=3206）· 接入点：3206-1 提交写作任务
> 计费：300 厘/次 · 请求方式：POST（content-type 为 multipart/form-data）· 返回格式：JSON
> 适用人群：需要控制内容来源与输出语言的开发者 · 阅读时间：约 7 分钟 · **最后实测核对：2026-09-15**
## 核心要点
- `topic` 是唯一必填参数，`reference_list`、`file`、`lang` 都可选，不传也能出稿。
- `3206-1` 的 content-type 是 `multipart/form-data`，`reference_list` 要作为**表单字段**提交，值是 JSON 数组字符串。
- `lang` 只接受 `zh` 和 `en`。2026-09-15 实测一次 `lang=en` 加 `file` 上传的 multipart 提交，HTTP 200、1.31 秒返回 `task_id`。
## 三个参数各管什么
精品长文一键写作的提交接入点是 `https://route.showapi.com/3206-1`，参数表里只有四个字段，其中三个可选。它们的分工是这样的：
| 参数 | 类型 | 必须 | 管什么 |
|------|------|------|------|
| `topic` | String | 是 | 写作要求。自然语言描述，示例值是「帮我写一篇关于DeepSeek的介绍」 |
| `reference_list` | String | 否 | 引用链接。JSON 数组字符串，接口会参考这些公开网页 |
| `lang` | String | 否 | 输出语言。`zh` 中文 / `en` 英文 |
| `file` | File | 否 | 引用文件。走 multipart 文件字段 |
三个可选参数都不传时，接口按 `topic` 自行检索公开网页上的信息再扩展成文。传了 `reference_list` 或 `file`，等于把内容来源收窄到你指定的范围。
## reference_list 怎么传
`reference_list` 的类型是 String，值是**一个 JSON 数组的字符串**。文档示例：
```
["https://www.showapi.com/apiGateway/view/872"]
```
注意这是字段的值，不是要你再包一层。用 Python 写就是 `json.dumps([...])`：
```python
import json
import requests
reference_list = json.dumps([
"https://www.showapi.com/apiGateway/view/3206",
"https://www.showapi.com/",
], ensure_ascii=False)
r = requests.post(
"https://route.showapi.com/3206-1",
params={"appKey": "YOUR_APPKEY"},
data={
"topic": "写一篇介绍 showapi 接口市场的短文",
"reference_list": reference_list,
"lang": "zh",
},
timeout=60,
)
print(r.json()["showapi_res_body"])
```
用 cURL 时引号要小心，JSON 里的双引号在 shell 里需要整体加单引号包住：
```bash
curl -X POST "https://route.showapi.com/3206-1?appKey=YOUR_APPKEY" \
-H "content-type: multipart/form-data" \
-F "topic=写一篇介绍 showapi 接口市场的短文" \
-F 'reference_list=["https://www.showapi.com/"]'
```
Node.js 侧用 `URLSearchParams` 或 `FormData` 都可以，值同样是 JSON 字符串：
```javascript
const fd = new FormData();
fd.append("topic", "写一篇介绍 showapi 接口市场的短文");
fd.append("reference_list", JSON.stringify(["https://www.showapi.com/"]));
fd.append("lang", "zh");
const resp = await fetch(`https://route.showapi.com/3206-1?appKey=${APPKEY}`, {
method: "POST",
body: fd,
signal: AbortSignal.timeout(60000),
});
```
如果 cURL 命令行里出现字符串被截断、接口报参数解析错误，先确认引号层级。JSON 数组里的 `[`、`]`、`"` 都是 shell 元字符，用 `-F` 加单引号包裹是最稳的写法。
## file 与 multipart 的配合
`file` 是 File 类型，只能用 multipart 请求体提交，也就是 `multipart/form-data` 这种编码。文档给出的 content-type 示例值正是 `multipart/form-data`。
cURL 用 `-F` 表示 multipart 字段，`@` 后面跟本地文件路径：
```bash
curl -X POST "https://route.showapi.com/3206-1?appKey=YOUR_APPKEY" \
-F "topic=Write a brief introduction to the ShowAPI open API marketplace" \
-F "lang=en" \
-F 'reference_list=["https://www.showapi.com/"]' \
-F "file=@D:/docs/ref.txt;type=text/plain"
```
Python 的 requests 用 `files` 参数传文件、用 `data` 传其余字段，两者会一起编成 multipart：
```python
with open("ref.txt", "rb") as f:
r = requests.post(
"https://route.showapi.com/3206-1",
params={"appKey": "YOUR_APPKEY"},
data={"topic": "写一篇介绍 showapi 接口市场的短文", "lang": "zh"},
files={"file": ("ref.txt", f, "text/plain")},
timeout=60,
)
```
**实测记录（2026-09-15）**：一次同时带上 `topic`、`lang=en`、`reference_list` 和 `file` 的 multipart 提交，接口返回 HTTP 200、耗时 1.31 秒、`showapi_res_code=0`、`showapi_fee_num=1`，`task_status` 为 `preparing`：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"topic": "Write a brief introduction to the ShowAPI open API marketplace",
"task_status": "preparing",
"remark": "文章正在生成中，请稍后！",
"task_id": "26d32f71742b40c2b7a91504e438c060",
"ret_code": 0
}
}
```
四个字段同传不会互相冲突，`file` 字段用 `text/plain` 的纯文本文件可以被接受。
## 引用是否生效，看正文末尾的 References
`reference_list` 和 `file` 都不会出现在返回字段里，但接口会把它们**列在正文末尾的 `## References` 小节**。2026-09-15 实测上面那次提交，最终取回的正文结尾是这样一个编号列表：
```
## References
1. [ref.txt](https://imgstorage.yicaiai.com/…/xxxx.txt)
2. [某接口介绍页](https://www.showapi.com/)
```
第一条对应 `file` 上传的文件，第二条对应 `reference_list` 里给的链接。要确认引用是否被采纳，读 `content` 的最后一个小节即可，不必靠正文内容去猜。
`lang` 只影响标题和正文的语言，`keywords` 字段仍返回中文。同一份返回里 `title` 是 `Exploring the ShowAPI Open API Marketplace: A Comprehensive Guide`，而 `keywords` 是 `ShowAPI`、`开放接口`、`API市场`、`开发者平台`、`云服务`。要英文关键词得自己在调用侧做映射。
## lang 只影响输出语言
`lang` 的取值文档只给了两个：`zh` 中文、`en` 英文。
它管的是**成稿语言**，不影响你提交的 `topic` 用什么语言写。上面那次实测就是英文 `topic` 配 `lang=en`，接口正常受理。中文 `topic` 配 `lang=en` 也是合法组合，文档没有对两者做一致性要求。
不传 `lang` 时的默认行为文档没有明确说明，要确定输出语言就显式传，别依赖默认值。
## 参数与返回的对应关系
提交时的 `topic` 会原样回显在 `3206-1` 的返回里，也会出现在 `3206-2` 的列表字段和 `3206-3` 的详情里（列表里的版本会被截断）。这意味着你可以用 `topic` 做一层业务侧的对账：提交时的值和你从列表里读到的前 20 个字符应当一致。
`reference_list` 和 `file` 不会出现在返回字段里。要确认引用是否生效，只能看正文内容是否围绕你给的来源展开。
## FAQ
**Q1：`reference_list` 传数组对象会报错吗？**
会。参数类型是 String，请传 JSON 字符串。Python 里先 `json.dumps()` 再放进表单字段。
**Q2：不传 `reference_list` 效果会差多少？**
接口会自己检索公开网页上的信息来扩展内容。你需要内容围绕指定来源时再传，接口本身没有要求必传。
**Q3：`file` 支持哪些格式？**
文档只标了 File 类型，没有列扩展名白名单。2026-09-15 实测用 `text/plain` 的 `.txt` 文件提交成功；其余格式建议先小样试一次再批量用。
**Q4：`file` 和 `reference_list` 能同时传吗？**
可以。实测同时带上 `topic`、`lang`、`reference_list`、`file` 的 multipart 请求正常返回 `task_id`。
**Q5：`lang=en` 会让 `task_status` 的取值变成英文吗？**
不会。状态字段的取值是固定的 `preparing` / `writing` / `success`，与 `lang` 无关。`lang=en` 影响的是标题和正文，`keywords` 字段实测仍返回中文。
**Q6：用 GET 方式能传这三个参数吗？**
文档标注请求方式为 POST/GET，但参数表里 `file` 是 File 类型、content-type 是 `multipart/form-data`，文件字段只能走 POST 请求体。带 `file` 的场景用 POST。
**Q7：怎么确认引用链接真的被用上了？**
看 `content` 末尾的 `## References` 小节，接口会把 `reference_list` 和 `file` 的来源按编号列出来。
**Q8：`file` 里的内容和 `reference_list` 的链接作用一样吗？**
两者都会进入 `## References` 列表作为参考来源，但不用把它们当成等价的输入；实测同时传两者时，正文参考列表里两个来源各占一条。它们分别用于不同的场景。
## 下一步阅读
- 完整调用流程：[用 Python 提交第一个写作任务并取回成稿](https://www.showapi.com/guides/longform-writing-quickstart-3206)
- 端到端链路设计：[从一句主题到带配图长文的完整链路](https://www.showapi.com/guides/longform-writing-pipeline-3206)
- 返回字段逐个说明：[返回字段与 ret_code 说明](https://www.showapi.com/guides/longform-writing-response-fields-3206)
- **本系列共 9 篇**：查看[精品长文一键写作指南总目录](https://www.showapi.com/guides/longform-writing-guides-3206)
