展开本页目录
开始前准备什么
- 准备自己有权使用的合成练习资料，不上传他人的录音或私密内容。
- 按官方文档核对当前平台、版本与套餐；本轮目标产品操作未执行，练习文件可离线查看。
- 准备文本输入契约
- 建立安全鉴权配置
- 提交视觉并保存真实ID
- 按状态接口等待
- 及时鉴权下载冻结
- 核对响应与错误分支
- 交付本地文件台账
1. 准备文本输入契约
将规则写成短文本，PDF等来源先合法提取文字。Napkin app有文件导入不等于API也接受文件，本API使用文本。
2. 建立安全鉴权配置
在Developers创建自己的token，用Authorization Bearer从安全环境读取。不要把token放到PPTX、图注、公开日志或图片URL。
3. 提交视觉并保存真实ID
按POST /v1/visual当前schema传content等实际字段，格式与语言逐项核对。计划中的request-id留空直到真实201返回，不用作者自编ID模拟成功。
官方界面与功能位置
以下为官方文档配图，具体版本与账号入口以当前产品为准。本课练习输入与验收对照见相邻步骤。
4. 按状态接口等待
用GET /v1/visual/{request-id}/status轮询并渐进放缓。完成后读取generated_files，不因只有请求ID就尝试发布图片。
5. 及时鉴权下载冻结
官方状态和文件链接从生成起约30分钟有效，下载也需鉴权。把实际文件保存到自己有权管理的持久位置，别让文章依赖临时URL。
6. 核对响应与错误分支
检查Content-Type、文件结构和哈希，遇到request_expired或no_credits按具体错误处理。错误JSON不能重命名成SVG来通过文件存在检查。
7. 交付本地文件台账
保存脱敏请求、实际ID、下载时间、格式和校验。未调用时仅提供请求计划与作者参考，不伪造临时链接或API图像。
下载本课材料并开始操作
练习包包含本课的具体输入、可编辑数据、正反样例与七步说明。index.html 可离线查看原件和验收参考，actual-results.csv 用于记录你实际操作后的结果。
怎样确认已经完成
- POST仅文本，不上传PDF；轮询与下载分别记录。
- 真实文件在有效期内鉴权下载并存本地，文章引用自有持久文件。
- 下载响应为目标格式且有校验值，错误JSON不保存成svg。
常见问题
Napkin API图片链接为什么过一会就失效？
把来源整理为文本，按当前 /v1/visual schema 提交并保存真实请求 ID，再查询状态。在下载 URL 有效期内按要求鉴权取回文件，检查内容类型后持久保存；临时链接不适合直接用作长期文章配图。
Napkin网页能导入PDF，API也能上传PDF吗？
当前API是文本输入，不能直接上传文档。先合法提取需要的文本，再按API schema提交。