三剪客 · 封面图批量生成
## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑一两条)。
拿到后填进环境变量A7W_API_KEY,或直接传给--key参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。
能做什么
给一批标题 / 选题(一个标题一行),批量产出各平台的封面图:
标题清单 ──► plan :每个标题 × 每个平台,出「画什么 / 大字写什么 / 放哪」
──► images :批量出**无字背景图**(真花钱,先报价,断点续跑)
──► overlay :把大字标题**本地渲染**压到图上(PIL,零成本、零网络)
它替代的是批量做号的人每天真正在做的那个动作:**不是"画一张封面",
而是"30 个标题 × 5 个平台 = 150 张封面,今晚要出完"**。
| 子命令 | 干什么 | 花钱吗 |
|---|---|---|
specs | 各平台封面规格(比例 / 目标像素 / 安全区 / 大字上限),零网络 | 零成本 |
plan | 按标题清单出封面方案 | 只花文本钱(一次调用,实测 1317 token / 4 条) |
images | 批量出无字背景图 | 真花钱,实测 24 点/张 = 0.24 元(1K),先报价 |
overlay | 本地叠大字标题(字号/断行/描边/阴影/安全区) | 零成本、零网络 |
all | 串起 plan → images → overlay,断点续跑 | 按阶段花钱 |
cost | 只算钱 | 零成本 |
models | 现查 api.a7w.cn 在架插件与模型 | 零成本 |
| 你最关心 | 答案 |
|---|---|
| 多少钱 | 出图实测 24 点/张(1K)= 0.24 元/张,1 元 = 100 点,跑之前先把总价打出来;文本那一步只花 token |
| 要多久 | 单张出图实测 5~40 秒;叠字每张 1~2 秒(纯本地) |
| 要装什么 | 零第三方依赖;叠字需要 PIL(pillow),没有就明确报降级(exit=2),不会静默出无字的图 |
| 支持哪些平台 | 小红书 3:4 / 公众号 2.35:1 / 视频号 16:9 / 抖音 9:16 / B站 16:9 |
| 图上文字会不会糊 | 不会:出图提示词里明确不许出现任何文字,大字由本地渲染压上去,文字不进模型 |
| 大字太长怎么办 | 拦截,并报出实际长度与多出来的那部分;绝不静默截断(见「叠字可读性」) |
| 中断了怎么办 | 断点续跑:已完成的图直接跳过、已提交未完成的用 task_id 续查(不重新提交、不重复扣费);连"任务完成了但下载崩了"都能靠断点补下载 |
| 会瞎编吗 | 方案提示词里写死不许编品牌、数字、logo、水印 |
与其他两个「工厂」的边界(改代码前先读这一段)
同族有三个「工厂」,输入与产出刻意不同,不要把它们当成一个包的三种参数:
| 输入 | 产出 | 大字标题怎么来的 | |
|---|---|---|---|
sanjianke-image-factory | 一篇文稿 / 一个主题 | 文章各段的配图(封面只是其中一种角色) | 写进出图提示词,让模型画进画面 |
sanjianke-xhs-note-factory | 一份母稿 | N 篇小红书笔记 + 每篇一张 3:4 封面 | 写进出图提示词(cover_text),让模型画进画面 |
| 本包 | 一批标题清单 | 同一标题 × 5 平台的封面矩阵 | 背景图无字 + 本地 PIL 渲染叠字 |
后者是本质差别:前面两个包全库里没有 ImageDraw / truetype 的代码路径
(它们用 PIL 只做裁剪),文字清晰度受出图模型摆布;本包把文字从模型手里拿回来了。
怎么用(命令行)
第 0 步:获取 API Key
到 api.a7w.cn 注册,创建一个 API Key(形如 sk-...)。
第 1 步:装依赖
零第三方依赖。 只要 Python 3.7+:
python3 --version
scripts/a7w.py 是所有 Skill 包共用的零依赖客户端(逐字节等于规范版,
SHA256 EACD2E4F…B465,任何包都不许为了业务改它);scripts/imgprobe.py 是图片头探针
(纯标准库 struct/zlib);scripts/run.py 同样只用标准库。
叠字要 PIL(
pillow)。它在,overlay就能跑;它不在,overlay会
明确报降级并退出 exit=2,而不是静默出一张没有字的图。背景图那一步(images)
不依赖 PIL,没有 PIL 也能出图(只是--snap会回落到内置 PNG 裁剪器)。
第 2 步:填 Key
# Linux / macOS
export A7W_API_KEY=sk-你的key
# Windows PowerShell
$env:A7W_API_KEY="sk-你的key"
# 或存进配置文件反复用(推荐)
python3 scripts/a7w.py login --key sk-你的key
第 3 步:先看平台规格(零网络、零成本)
python3 scripts/run.py specs
会打印每个平台的比例、目标像素、叠字安全区(像素)、字号与大字字数上限,
并做一次口径自检(该字号下上限字数是否真的放得进安全区)。
第 4 步:出方案(只花文本钱)
python3 scripts/run.py plan --file 标题清单.md --out plan.json
标题清单就是一行一个标题(# 开头算注释):
# 我的标题清单
三分钟学会封面排版
批量出图到底省了谁的时间
也可以不给文件:
python3 scripts/run.py plan --text "标题一,标题二" --platform xiaohongshu --platform douyin
想先看不花钱的提示词:
python3 scripts/run.py plan --file 标题清单.md --dry-run
第 5 步:先算钱(不出图)
python3 scripts/run.py cost --titles 30 --count 5 # 30 个标题 × 5 平台 = 150 张
# 150 张 × 24 点/张(1K,实测价)= **3600 点 = 36.00 元**
python3 scripts/run.py cost --titles 30 --count 5 --budget 1000
# 超预算 → 打印「images / all 会在提交前被拦下」并返回退出码 3
第 6 步:出背景图(真花钱)
# 先不带 --yes 跑一次:只报价,不提交(退出码 4)
python3 scripts/run.py images --plan plan.json --outdir ./out
# 确认了再加 --yes;--snap 让产出按平台设计比例裁准
python3 scripts/run.py images --plan plan.json --outdir ./out --yes --snap \
--budget 400 --report evidence.json
图片一定要输出到包外(比如 ./out、%TEMP%\...)。Skill 包的上传白名单只收.md .py .txt .json .sh .js .yaml .yml .csv,图片会让上传 400;脚本也会拒绝把--outdir 指到包内(退出码 2)。
第 7 步:本地叠大字标题(零成本、零网络)
python3 scripts/run.py overlay --plan plan.json --outdir ./out
# 产物:./out/xiao-01_xiaohongshu_cover.png 等,像素按平台目标(如 1080x1440)
想先看排版(不渲染、不写文件):
python3 scripts/run.py overlay --plan plan.json --outdir ./out --dry-run
换字体、换配色:
python3 scripts/run.py overlay --plan plan.json --outdir ./out \
--font "D:\fonts\AlibabaPuHuiTi-Bold.ttf" \
--text-color "#FFFFFF" --stroke-color "#101010"
完整工作流(一条命令)
python3 scripts/run.py all --file 标题清单.md --outdir ./out --yes --snap --budget 400
重跑同一条命令:方案文件已存在就跳过 plan(不重复花文本钱),
已出的背景图直接跳过(不重复扣费),叠字按内容与样式判定是否重渲染。
直接用 curl 调(不依赖本包脚本)
底层就是算力集市 api.a7w.cn 的标准两步异步任务。提交(注意没有 /generate 这个端点,
"文生图"是 submit 的 action=generate 参数):
# 算力集市 api.a7w.cn · nano_banana 提交出图(真花钱,1K 约 24 点/张)
curl -sS -X POST "https://api.a7w.cn/api/v1/apps/nano_banana/submit" \
-H "Authorization: Bearer $A7W_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "竖版俯拍桌面,浅米色木纹台面,几张卡纸错落排开,左上四十五度斜射柔光,暖白偏冷灰调,**画面中不要出现任何文字**",
"action": "generate",
"model": "nano-banana",
"resolution": "1K",
"aspect_ratio": "3:4"
}'
拿 data.task_id 去轮询:
curl -sS "https://api.a7w.cn/api/v1/tasks/task_xxxxxxxxxxxx" \
-H "Authorization: Bearer $A7W_API_KEY"
参数说明
全局
| 参数 | 说明 |
|---|---|
--key | 临时指定 Key;优先级最高。别把它写进脚本或文档 |
--json | 以 JSON 输出,写在子命令前面或后面都可以;JSON 模式下 stdout 只有一个完整 JSON,报价与进度走 stderr |
--version | 打印版本号 |
标题清单输入(plan / all 共用)
| 参数 | 说明 |
|---|---|
--file <文件> | 推荐。标题清单,一行一个;# 开头算注释;自动剥 BOM |
--text "标题1,标题2" | 直接给标题;逗号与换行都当分隔符 |
| 位置参数 | 同上,可给多个文件 |
--titles N | 最多取前 N 个标题,默认 200 |
--platform | 目标平台,可重复:xiaohongshu / wechat / shipinhao / douyin / bilibili;默认 5 个全出 |
--style | 统一视觉风格口径(会给到模型) |
--brief | 作者补充要求 |
plan —— 出封面方案
| 参数 | 说明 |
|---|---|
--out | 把方案写成 JSON,images / overlay / all 要用它 |
--dry-run | 只打印将发送的提示词,不调模型、不花钱 |
--model / --temperature / --max-tokens | 文本模型参数,默认 deepseek-chat / 0.7 / 8192 |
--no-json-mode | 不要求上游返回 JSON 对象 |
images —— 批量出背景图
| 参数 | 说明 |
|---|---|
--plan | 必填。plan 产出的方案 JSON |
--outdir | 图片输出目录,默认 %TEMP%\cover-factory-out;不可是包内目录(退出码 2) |
--platform / --count / --only | 只出指定平台 / 前 N 条 / 指定 id |
--resolution | 1K(默认)/ 2K / 4K。只有 1K 有实测价;2K/4K 不给单价就拒绝估算(退出码 3) |
--points-per-image | 覆盖单张单价(点) |
--budget | 成本上限(点)。预估超了直接停;跑的过程中每次提交前还会再核一次 |
--yes | 确认真的花钱。不加就只报价(退出码 4),一个任务都不提交 |
--snap | 出图后按平台设计比例居中裁剪,裁完再读一次文件头复核,只把真正裁准的记成合格 |
--ratio-tolerance | 比例容差,默认 0.03(实测最大偏差 2.9%);有 0.0025 的量化地板 |
--poll-timeout | 单张轮询超时秒数,默认 600(上限,不是期望时长) |
--max-seconds | 整批最长耗时,到点中断(退出码 5),已完成的都在断点文件里,重跑可续 |
--state | 断点文件路径,默认 <outdir>/cover-factory-state.json |
--force | 忽略断点全部重出(会重复扣费) |
--no-wait | 只提交不等待(之后用 task_id 续查) |
--stop-on-error | 一张失败就整体停 |
--report | 把本次证据(请求参数 / 任务原文 / 真实像素 / 真实扣费)写成 JSON |
--allow-prompt-hits | 提示词命中闸门也出图(默认拦截)。不接受它放行超长大字 |
overlay —— 本地叠大字标题
| 参数 | 说明 |
|---|---|
--plan | 必填。方案 JSON(大字标题从 items[].overlay.text 取) |
--outdir | 底图所在目录(也是产物目录);不可是包内目录 |
--outdir-name | 叠字产物另存到一个目录 |
--font | 指定中文字体文件(.ttf / .ttc / .otf)。不给就在系统字体里找 |
--text-color | 大字颜色,如 #FFFFFF。不给用平台默认 |
--stroke-color | 描边颜色,如 #101010。不给用平台默认 |
--no-shadow | 不画阴影层(亮底图上可读性会下降) |
--dry-run | 只算排版并打印(字号 / 行数 / 渲染框 / 安全区),不渲染、不写文件 |
--force | 忽略叠字断点重新渲染(零成本,随便用) |
--platform / --count / --only | 只叠指定范围 |
cost —— 只算钱不出图
| 参数 | 说明 |
|---|---|
--count N | 要出几张 |
--titles N --platform p1 --platform p2 | 按「标题数 × 平台数」算总数 |
--resolution | 1K(默认)/ 2K / 4K |
--points-per-image | 覆盖单张单价(点)。2K/4K 必须给 |
--budget | 预算上限(点),超了退出码 3 |
平台规格(specs 的数据源)
| preset | 平台 | 设计比例 | 生成用 aspect_ratio | 目标像素 | 大字上限 | 字号 / 描边 | 大字对齐 |
|---|---|---|---|---|---|---|---|
xiaohongshu | 小红书 | 3:4 | 3:4 | 1080x1440 | 16 字 | 80px / 5px | 居中偏下 |
wechat | 公众号 | 2.35:1 | 21:9 | 900x383 | 14 字 | 76px / 4px | 左(分享只看左半) |
shipinhao | 视频号 | 16:9 | 16:9 | 1080x608 | 16 字 | 78px / 5px | 居中偏下 |
douyin | 抖音 | 9:16 | 9:16 | 1080x1920 | 14 字 | 96px / 6px | 居中(避开底部/右侧) |
bilibili | B站 | 16:9 | 16:9 | 1146x717 | 16 字 | 78px / 5px | 居中偏下 |
(= 2.333:1)。所以本包用 21:9 生成、再用 --snap 裁到 2.35:1。这是明确的设计取舍。
七道本地硬闸门
闸门都是拦截 + 标红 + stderr 汇总 + 退出码非 0,不是"提示一下"。
因为出图是按次扣费的,事后发现问题的代价是真金白银。
1. 合规 —— 广告法违禁词(「最X」有豁免,句首不豁免)
绝对化用语(最/第一/国家级/100%)、虚构权威背书、医疗功效、投资承诺、站外导流,
命中即拦。这一条对出图提示词与大字标题同样适用。
「最X」的可枚举上下文豁免(口径逐字继承同族模板):
「做菜和剪辑最大的共同点是……」「新手最容易踩的坑是……」
这类是文章/标题的正常中文,不是给商品贴"最大"的标签。豁免范围**写死在代码里、
可枚举、可复核:命中「最X」后,后文落在 SUPERLATIVE_OK_AFTER 表里且不在句首**才放行。
⚠️ 句首不许误豁免。「最大区别是……」这种句首写法经常正是标题式的最高级宣称。
封面大字标题恰恰几乎全在句首,所以这条对本包比对同族更关键。
豁免只允许一个「的」(「最大的共同点」放行),不为逗号/顿号开豁免 ——
开了那个后门,「最好的工具,值得买」也会被放行。这是已知的保守行为,靠改文案解决。
2. 占位符残留
{}、{{标题}}、[待填]、[待补充]、XXX、(此处省略)、TODO/TBD。[1](引用序号)这类是正常写法,不会被误拦。
3. prompt_echo —— 模型会照抄提示词里的示例
这条是从标题工坊的事故来的:提示词里写过的示例,哪怕明确标着"这是错的写法",
模型照样照抄——公众号那一轮最高分 89.0 的标题一字不差就是提示词里的示例。
判定三条,任一即命中:
| 判据 | 阈值 |
|---|---|
| 去标点后完全相同 | exact |
| 字符二元组 Jaccard | ≥ 0.75 |
| 示例的二元组覆盖度 | ≥ 0.60 |
第三条是补漏:出图提示词动辄 60~120 字而示例只有 25 字,Jaccard 的分母是两份二元组的
并集,示例那侧被摊薄得极狠。实测(同族):示例原样嵌入 + 补 9 个字(34 字)
→ Jaccard 0.727(旧判据放行 ❌)但覆盖度 1.000(新判据拦 ✓);
示例嵌进 102 字的六段结构提示词 → Jaccard 0.245(漏)、覆盖度 1.000(抓住)。
长度守卫是相对的:max(6, len(示例)//2),短串不比(二元组集合太小、指标虚高)。
真实产出与示例之间有17 倍以上的安全距离(真实业务提示词 Jaccard 只有 0.042 / 0.000)。
4. 出图比例真伪 —— 读回真实像素,不信自报字段
不信接口返回里的任何比例字段,把图下载回来读文件头,用真实宽高算比例。
⚠️ 实测到的上游特性:上游不是按比例给像素,而是先定总像素、再把每边向下对齐到
32 的倍数。所以 10 种比例里有 5 种拿不到像素级精确比例:
| 请求 | 实测像素 | 实际比例 | 偏差 |
|---|---|---|---|
| 3:4 | 864x1184 | 0.7297 | 2.70% |
| 16:9 | 1344x768 | 1.7500 | 1.56% |
| 9:16 | 768x1344 | 0.5714 | 1.56% |
| 21:9 | 1536x672 | 2.2857 | 2.04% |
| 1:1 / 4:3 / 2:3 / 3:2 | — | 精确 | 0% |
所以默认容差是 3%(容差内不算"假",但真实像素与偏差照样打印出来,不藏),
并且有 0.0025 的容差地板(像素是整数,"裁到精确比例"本身就有量化误差:
2.35:1 裁后偏差 0.0925%)。
要拿到像素级精确比例就加 --snap:按平台设计比例居中裁剪,裁完再读一次文件头复核,
只会把真正裁准的记成合格。优先用 PIL;没有 PIL 时回落到内置的 8 位 PNG 裁剪器
(只用 zlib + struct),两条路都走不通时如实报告"没能裁",不假装成功。
5. 叠字可读性 —— 本包独有的那道(绝不静默截断)
| 判什么 | 结果 |
|---|---|
| 大字标题超过平台上限 | 拦截 + 标红 + 退出码 3,报出实际长度与多出来的是哪几个字 |
| 字号缩小到地板仍未放不进去 | 拦截,不静默缩小到看不清 |
| 叠字渲染框越出安全区 | 标红,退出码 3 |
| 没有大字标题 | 拦截,拒绝产出一张没有字的封面 |
上限是算出来的,不是拍的:可用宽度 = 目标宽 × (1 − 左右安全区);一个汉字在 PIL 里
的宽度 ≈ 字号(实测 80px 字体下 16 个汉字 bbox 宽 1280px = 16 × 80);max_chars 就是按这个字号能放下的字数。specs 会做口径自检,不一致就报出来。
为什么这条是硬拦而不是截断:同族
sanjianke-xhs-note-factory1.0.4 及以前写的是cover_text[:20]—— 静默截断:用户改了封面文案、付了钱重出图,只有第 21 字之后被砍掉,
图看起来一模一样,用户以为"我的改动生效了"。本包从一开始就照它 1.0.5 修好的口径做:
超限即拦截,一个字都不许静默丢。
而且不接受--allow-prompt-hits放行超长大字 —— 放行等于回到静默截断。
这个闸门在花钱之前就判(plan与images都判):标题太长就别出背景图了。
6. 成本上限
- 提交任何任务之前先算总价;超
--budget直接停,一个任务都不提交 - 每张提交前再核一次:前面真实扣费可能比预估高,超了就就地停
2K/4K没有实测单价 → 拒绝估算,退出码 3。宁可拒绝也不编一个数
(想估就给 --points-per-image)
7. 产出图不许进包
--outdir 指到包内 → 退出码 2(在花钱之前就拦下)。包内只放文本。
断点续跑:key 必须含全部影响产出的维度
⚠️ 这一节是本包最容易写错的地方,改代码前必读。
本包的出图产出由 6 个维度决定,一个都不能少:
提示词全文摘要(不是前缀截断) + 比例 + resolution + 模型 + 叠字内容 + 叠字样式
后两维是本包特有的 —— 这就是「标题清单驱动 + 本地叠字」的直接后果:
只改了大字标题(背景图一个字没改)也必须重出,否则图上的字是旧的。
同族在这件事上踩过三次,三次的形态都是静默复用过期产物:
| 踩过的形态 | 后果 |
|---|---|
_norm_for_echo(prompt)[:24] 截断取摘要 | 提示词只改第 25 字之后 → key 不变 → 复用旧图 |
resolution 不入 key | 先跑 1K、改成 4K 重跑 → 复用 1K 的图,用户以为拿到 4K |
| 断点记录里的值与本次不一致却照样跳过 | 静默复用说不清来历的旧产物 |
本包的做法:
prompt_digest对全文取 sha1,绝不用prompt[:N]resolution/gen_ratio/model直接进 key- 叠字内容与样式也进 key(
overlay_style_sig:文本 + 平台 + 字号 + 描边 + 位置 + 字体) - 命中 key 之后逐维复核记录里的值;对不上就打印一行「不复用旧图」并重出
- 跳过的那张也要重新读一遍真实像素过比例闸门(断点文件可能被手工改过)
- 任务已完成但下载崩了:断点里存了
task_id与image_url,
重跑会补下载(0 点),而不是重新提交(再扣一次)
排错
| 现象 / 报错 | 原因 | 怎么办 |
|---|---|---|
鉴权失败(401) | Key 无效、过期或写错 | 到 https://api.a7w.cn/ 重新领取;确认没把 Bearer 重复写进环境变量 |
| 点数不足(HTTP 402) | 账号点数用完 | 到 https://api.a7w.cn/ 充值后重试 |
code: 0 但 HTTP 是 200 | 网关信封里 code == 1 才是成功,不是 0 | 看 body 里的 msg;脚本已按这个口径判断,别改成 code == 0 |
当前请求未命中可用计费规格 | model 与 resolution 组合不支持 | 普通 nano-banana 只支持 1K;要高清档换 nano-banana-2:official 之类 |
轮询一直 processing | 上游排队 | 有 --poll-timeout(默认 600 秒)与断点;重跑会用 task_id 续查、不重新提交 |
这是一次真花钱的操作…确认后加 --yes(exit 4) | 成本前置生效,这是正常的,不是错误 | 看过报价后加 --yes 或 --budget 重跑 |
大字标题 N 字,超过 X 上限 M 字(多出 …)(exit 3) | 叠字可读性闸门 | 把超出的部分移到正文,或拆成两张。不接受 --allow-prompt-hits 放行 |
没有找到可用的中文字体(exit 2) | 系统里没有中文字体 | 用 --font 指一个 .ttf/.ttc/.otf;specs 会打印可用字体 |
本地叠字需要 PIL(exit 2) | 没装 pillow | pip install pillow 后原样重跑(背景图不会重出、不重复扣费);或只用 images 出无字底图 |
2K 档没有实测单价,拒绝凭猜估算 | 我们没有 2K/4K 的实测价 | 给 --points-per-image 指定单价,或先用 1K 出 |
输出目录 … 在 Skill 包内(exit 2) | --outdir 指到了包里的目录 | 换到包外(./out、%TEMP%\...)。包内放图片会让上传 400 |
!! 已花 … 点,再出下一张会超过 --budget(exit 3) | 真实扣费累计超了 | 已完成的产出仍在,从断点继续 |
| 重跑又扣了一次钱 | 提示词/叠字样式/分辨率改了 → 断点 key 变了 | 这是设计如此(改了就该重画)。想省钱就别改,直接重跑即可跳过 |
改了 overlay.text 但图上的字是旧的 | 正常情况会重出(叠字内容进了 key) | 仍拿到旧图:断点文件是旧版本生成的,重跑一次;要无条件重出加 --force |
模型返回的不是合法 JSON | 模型在 JSON 前后多吐了字符 | 脚本已用 json.JSONDecoder.raw_decode 扫第一个完整对象。仍失败就加 --no-json-mode 并换模型 |
| Windows 下中文乱码 | 控制台代码页不是 UTF-8 | 先 chcp 65001,或设 PYTHONIOENCODING=utf-8 |
收集排错信息时请附上:完整命令、plan --dry-run 的输出、--report 产出的证据 JSON、原始报错文本。
不要在报错信息或截图里带上你的 API Key。
退出码(可直接用于流水线)
| 退出码 | 含义 |
|---|---|
0 | 全部成功且闸门全绿 |
1 | 没预料到的异常(代码 bug);--json 下给 kind=internal 信封 + stderr 打完整栈 |
2 | 参数/配置错误(含 --outdir 指到包内、没有字体、没有 PIL) |
3 | 有硬闸门命中(合规 / 占位符 / 照抄示例 / 比例 / 叠字可读性 / 超预算) |
4 | 还没花钱:需要 --yes 确认;或调用失败(网络 / 鉴权 / 点数 / 模型名) |
5 | 达到 --max-seconds 上限中断(可续跑) |
130 | 用户中断(Ctrl+C) |
--json 输出契约(给流水线与 agent 消费,只在 --json 下生效):
- stdout 上永远只有一个 JSON 文档(人读文案一律走 stderr),且顶层是 dict、带
ok - 成功:结果对象里多一个
"ok": true - 失败:stdout 输出一个 JSON 信封,形如
{"ok": false, "exit": 3, "error": {"kind": "gate", "message": "…"}}
(exit 就是本次真实退出码),kind 取 gate / usage / budget / call /interrupt / internal
- 闸门命中属于"跑成功了但结果不合格":此时结果 JSON 已经吐出去了
(ok: false 写在那个结果里),不再补信封 —— 否则 stdout 上会出现两个 JSON 文档,
消费方 json.loads 直接报 Extra data。这是实测踩过并修掉的一条
internal是没预料到的异常(代码 bug)的兜底:stdout 给信封、
完整 traceback 原样打到 stderr、退出码固定 1 —— 报 bug,不藏 bug
--json写在子命令前面或后面都可以(前后输出逐字节相同)
成本口径
| 项 | 实测 |
|---|---|
nano_banana 1K 出图 | 24 点/张 = 0.24 元 |
| 充值比例 | 1 元 = 100 点 |
| 提交时冻结 | 实测 frozen_points = 31.2(预冻结,不是最终扣费) |
| 完成后结算 | usage.points_cost = 24 |
| 失败 | 全额退回 |
| 文本(出方案) | 只出 token:实测 4 条方案 prompt 679 + completion 638 = 1317 token;网关不公布文本模型单价,金额要你自己填 |
| 本地叠字 | 0 点(纯本地渲染) |
只信 usage.points_cost。 平台的 pricing_matrix / tenant_* 字段我们验证过半数不可信:image_human 字段写 1.5/2/4/8 点/秒、实测 2/3/6/12;voice_tts/stt 字段写 30、实扣 40。frozen_points 也不是最终扣费:实测冻结 31.2、实扣 24,差 30%。
文件结构
sanjianke-cover-factory/
├── SKILL.md 本文件
├── README.md 给人看的说明
├── LICENSE.md MIT,署名三剪客
├── references/
│ ├── cover-design.md 封面设计方法论(构图、大字排版、安全区、配色)
│ ├── platform-specs.md 五个平台的封面规格矩阵、32 对齐与 --snap
│ └── cost-and-troubleshooting.md 计费口径、实测数据与排错手册
└── scripts/
├── a7w.py api.a7w.cn 零依赖客户端(**逐字节等于规范版,本包不改它**)
├── imgprobe.py 图片头探针:读真实像素 PNG/JPEG/GIF/WebP(只读,纯标准库)
└── run.py specs / plan / images / overlay / all / cost / models
约定:
scripts/a7w.py是所有 Skill 包共用的零依赖客户端,我们靠
「包内副本 SHA256 == 规范版」批量校验各包的客户端有没有被意外改坏。
所以本包没有为了自己的业务去改它——需要读图片像素就独立出imgprobe.py,
需要下载图片就在run.py里自带一小段 urllib(a7w._request是给 JSON 用的,
它的raw=参数是原始请求体、不是"要原始响应",拿它下 PNG 会踩两个坑,见download的注释)。
端点速查
算力集市(api.a7w.cn)的出图是两步异步任务:
| 用途 | 方法与路径 |
|---|---|
| 提交出图任务 | POST https://api.a7w.cn/api/v1/apps/nano_banana/submit |
| 查任务结果(本包用它) | GET https://api.a7w.cn/api/v1/tasks/<task_id> |
| 查任务结果(应用级,备用) | GET https://api.a7w.cn/api/v1/apps/nano_banana/query?task_id=<task_id> |
| 看某应用的接口与参数 | GET https://api.a7w.cn/api/v1/apps/nano_banana |
| 在架应用清单 | GET https://api.a7w.cn/api/v1/apps |
| 在架模型清单 | GET https://api.a7w.cn/api/v1/models |
| 出方案用的大模型 | POST https://api.a7w.cn/api/v1/chat/completions |
没有 /generate 这个端点。 「文生图」是 submit 的 action=generate 参数。
submit 的参数名(用 python3 scripts/a7w.py schema nano_banana 实查,别猜):prompt / action(generate|edit) / resolution(1K|2K|4K) / aspect_ratio / image_urls / model / callback_url
—— 实查结果显示 query 是 POST(不是 GET),参数只有 task_id。
⚠️ status 在 data 顶层,不在 data.result 里。 平台文档写的是 data.result.status,
实测不对。照文档写会永远读不到状态、一路轮询到超时。
联系我们
- 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
- 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
- 更多 AI 插件与接口:AI 插件市场。
相关链接
- 算力集市 api.a7w.cn(注册领 Key):https://api.a7w.cn/
- 封面设计方法论:
references/cover-design.md - 平台规格矩阵:
references/platform-specs.md - 计费口径与排错:
references/cost-and-troubleshooting.md
免责声明:本包内置的违禁词表与判定口径是启发式自检工具,来自公开经验整理,
不构成法律意见,也不代表任何平台的官方审核标准。
封面的版权、肖像权、商标权与合规责任由使用者承担;
涉及真人、品牌 logo、医疗健康、金融等高风险内容必须人工复核后再发布。