三剪客 · 头像写真工坊
## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑几张)。
拿到后填进环境变量A7W_API_KEY,或直接传给--key参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。
能做什么
给人像照或一段人设描述 + 一个内置风格包,批量产出成套的头像与写真:
头像 1:1、社交封面 3:4、横版 16:9,按「风格包 × 比例 × 变体」展开成矩阵。
它替代的是做个人 IP 时最费神的那一步:不是"没有图",而是"三张图摆在一起像不像一个人"。
四条命令,只有最后一条花钱:
| 命令 | 做什么 | 花钱吗 | 联网吗 |
|---|---|---|---|
styles | 列出六个内置风格包与三个比例的完整字段 | 不花 | 不联网 |
plan | 出拍摄方案(机位/光线/背景/着装/姿态/后期 + 出图提示词) | 不花 | 不联网 |
cost | 只算钱不出图 | 不花 | 不联网 |
gen | 按方案批量出图 | 真花钱,先报价,要 --yes 才提交 | 联网 |
plan是本地确定性矩阵展开,不调用大模型——因为本包的方案是矩阵式的
(风格包 × 比例 × 变体),每一格的机位/光线/背景/着装/姿态/后期都由风格包与预设决定,
语义上不需要模型补全。于是「真花钱」的操作只剩gen一个,成本前置反而更干净。
这是本包相对同族配图工厂的一个刻意改动,理由见「已知取舍」。
| 你最关心 | 答案 |
|---|---|
| 多少钱 | 实测 24 点/张(1K)= 0.24 元/张,1 元 = 100 点;gen 跑之前会先把总价打出来 |
| 要多久 | 单张实测 5~60 秒完成;轮询有超时上限,不会无限等 |
| 要装什么 | 什么都不用装,只用 Python 标准库 |
| 支持哪些比例 | 头像 1:1 / 社交封面 3:4 / 横版 16:9 |
| 有几个风格包 | 内置 6 个,可自建(见 references/style-packs.md) |
| 中断了怎么办 | 断点续跑:已完成的图直接跳过,已提交未完成的用 task_id 续查,不重复扣费;但断点 key 含提示词——提示词一改就重出重扣,见排错表「重跑又扣了一次钱」 |
| 会瞎编吗 | 方案里不许编真人姓名、品牌、数据;人物合规与未成年人闸门挡在最前面 |
| 图生图要不要本地上传 | 不用也不能:上游只接受公网 HTTP/HTTPS 图片地址,没有上传接口(见下) |
怎么用(命令行)
第 0 步:获取 API Key
到 api.a7w.cn 注册,创建一个 API Key(形如 sk-...)。
第 1 步:装依赖
零依赖。 不需要 pip install 任何东西,只要机器上有 Python 3.7+:
python3 --version
scripts/a7w.py 是零依赖客户端(只用 urllib / json / mimetypes),scripts/imgprobe.py 是图片头探针(只用 struct / zlib),scripts/run.py 同样只用标准库。
PIL 不是必需的——它的存在只会让 --snap 支持更多图片格式。
约定:
scripts/a7w.py是所有 Skill 包共用的零依赖客户端,我们靠
「包内副本 SHA256 == 规范版」批量校验各包的客户端有没有被意外改坏。
所以本包没有为了自己的业务去改它——需要读图片像素就独立出imgprobe.py,
需要应用专属接口就写在run.py里。
第 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 styles
会打出六个风格包的光线、背景、着装、后期原文,以及三个比例的设计口径与安全区说明。
第 4 步:出拍摄方案(免费、不联网)
# 一个风格包 × 三个比例 = 3 张
python3 scripts/run.py plan --style business --out plan.json
# 两个风格包 × 两个比例 × 2 个姿态变体 = 8 张
python3 scripts/run.py plan --style business --style literary \
--preset avatar --preset cover34 --variants 2 --out plan.json
# 人设写得越具体,出图越稳
python3 scripts/run.py plan --style literary \
--subject "三十五岁男性,短发微卷,细框眼镜,气质沉稳,东亚面孔" \
--preset avatar --preset cover34 --out plan.json
第 5 步:先算钱(不出图)
python3 scripts/run.py cost --count 3
# 预估成本:3 张 × 24 点 = 72 点 = 0.72 元
python3 scripts/run.py cost --count 3 --budget 50
# 超预算 → 打印「gen 会被拦下」并返回退出码 3
python3 scripts/run.py cost --count 3 --resolution 2K --points-per-image 40
# 2K/4K 没有实测单价,不给 --points-per-image 就直接退出 3
第 6 步:出图(真花钱)
# 先不带 --yes 跑一次:只报价,不提交
python3 scripts/run.py gen --plan plan.json --outdir ./out
# 确认了再加 --yes;--snap 把 3:4 / 16:9 裁到像素级精确
python3 scripts/run.py gen --plan plan.json --outdir ./out --yes --snap \
--budget 200 --report evidence.json
图片一定要输出到包外(比如 ./out、%TEMP%\...)。Skill 包的上传白名单只收.md .py .txt .json .sh .js .yaml .yml .csv,图片会让上传失败;脚本也会拒绝把 --outdir
指到包内(退出码 2)。
中断了就原样重跑,提示词没变就不会重复扣费(断点 key 含提示词,改了会重出重扣):
python3 scripts/run.py gen --plan plan.json --outdir ./out --yes
# [1/3] #1 已完成,跳过(上次扣费 24.0 点,不再重复扣)
# [2/3] #3 发现未完成的 task_id=task_xxx,续查而不重新提交
第 7 步:复核产出(免费、不联网)
python3 scripts/run.py verify ./out/*.png --ratio 3:4
# 比例复核:请求 3:4,容差 3.00%(真实像素来自文件头,不信任何自报字段)
# [合格] ./out/1-cover34-3x4-xxxx.png 真实像素 864x1152 (3:4) 偏差 0.00% png
图生图:以真实照片为基础改风格
python3 scripts/run.py gen --plan plan.json --outdir ./out \
--photo-url "https://你的图床/portrait.jpg" --yes
给了 --photo-url 就是 action=edit(图生图),参考图地址直接透传给上游。
api.a7w.cn 的 nano_banana 插件只有
submit与query两个接口,
没有本地文件上传接口,所以本地照片必须先自己放到可访问的位置再传 URL。
用别人的照片做图生图必须事先取得本人授权——闸门不能替你判断你有没有这个权利。
完整工作流
# 0) 认风格包(免费,不联网)
python3 scripts/run.py styles
# 1) 看网关通不通、在架模型有哪些
python3 scripts/run.py models
# 2) 出方案(免费,不联网)
python3 scripts/run.py plan --style business --style neon \
--preset avatar --preset cover34 --preset wide --variants 1 --out plan.json
# 3) 算钱 + 设预算
python3 scripts/run.py cost --count 6
python3 scripts/run.py cost --count 6 --budget 200
# 4) 真出图(报价 → 确认)
python3 scripts/run.py gen --plan plan.json --outdir ./out
python3 scripts/run.py gen --plan plan.json --outdir ./out --yes --snap \
--budget 200 --report evidence.json
# 5) 复核比例
python3 scripts/run.py verify ./out/*.png --ratio 1:1
直接用 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": "1:1"
}'
拿 data.task_id 去轮询(status 在 data 顶层,不在 data.result 里):
curl -sS "https://api.a7w.cn/api/v1/tasks/task_xxxxxxxxxxxx" \
-H "Authorization: Bearer $A7W_API_KEY"
图生图则把 action 换成 edit 并带上 image_urls:
{
"action": "edit",
"prompt": "把背景换成深灰纯色棚拍,保留人物五官与发型不变,胸部以上近景",
"model": "nano-banana",
"resolution": "1K",
"aspect_ratio": "1:1",
"image_urls": ["https://你的图床/portrait.jpg"]
}
参数说明
全局
| 参数 | 说明 |
|---|---|
--key | 临时指定 Key;优先级最高。别把它写进脚本或文档 |
--json | 以 JSON 输出,写在子命令前面或后面都可以。plan --json --out plan.json 落盘的是纯 JSON,可直接喂给 gen;JSON 模式下 plan 会把报价一起放进同一个对象(stdout 只有一个完整 JSON,管道里 json.loads 不会炸) |
styles —— 列出内置风格包
零网络、零成本。--json 输出完整字段,便于程序消费。
plan —— 出拍摄方案
| 参数 | 说明 |
|---|---|
--style | 风格包,可重复:business / literary / studiobw / neon / film / guofeng;默认 business |
--preset | 比例预设,可重复:avatar(1:1) / cover34(3:4) / wide(16:9);默认三个全出 |
--variants | 每个「风格 × 比例」出几个姿态变体,默认 1。只轮换姿态,光线/背景/着装/后期不变 |
--subject | 人设描述(年龄、性别、发型、气质等),会织进每条提示词 |
--count | 最多保留几条(截断矩阵) |
--person-blocklist | 外挂人物名单文件(一行一个名字,命中即拦) |
--out | 把方案写成 JSON,gen 要用它 |
--points-per-image | 覆盖单张单价(点),只影响报价 |
gen —— 按方案批量出图
| 参数 | 说明 |
|---|---|
--plan | plan 产出的方案 JSON(与 --prompt 二选一) |
--prompt | 直接给一条出图提示词出图(提示词原样使用,不被模板改写) |
--style / --preset | 从方案里过滤,可重复 |
--ratio | 只配 --prompt 用:覆盖生成比例,如 3:4 |
--photo-url | 参考图公网 URL,可重复;给了就是 action=edit 的图生图 |
--action | generate / edit;默认按有没有 --photo-url 推断 |
--model | 出图模型,默认 nano-banana。用 models 或在架模型清单现查 |
--resolution | 覆盖分辨率 1K / 2K / 4K;2K/4K 无实测单价,须配 --points-per-image |
--count | 最多出几张(截断方案) |
--outdir | 图片输出目录,默认 %TEMP%\portrait-studio-out;不可是包内目录(否则退出码 2) |
--budget | 成本上限(点)。预估超了直接停;每张提交前还会再核一次 |
--points-per-image | 覆盖单张单价(点) |
--yes | 确认真的花钱。不加就只报价、一个任务都不提交 |
--snap | 出图后按请求比例精确裁剪(见「比例那件事」) |
--snap-when | nonzero(默认,偏差 > 0 就裁准)/ overtolerance(只在超容差时裁) |
--snap-on-design | 按设计比例(design_ratio)裁,而不是按生成比例 |
--ratio-tolerance | 比例容差,默认 0.03(实测最大偏差 2.70%);有 0.0025 的量化地板 |
--poll-timeout | 单张轮询超时秒数,默认 600(上限,不是期望时长;实测 5~60 秒完成) |
--poll-interval | 轮询间隔秒数,默认 5 |
--max-seconds | 整批最长耗时,到点中断(退出码 5),已完成的都在断点文件里,重跑可续 |
--state | 断点文件路径,默认 <outdir>/portrait-studio-state.json |
--force | 忽略断点全部重出(会重复扣费,只在确实要重画时用) |
--no-wait | 只提交不等结果(稍后用 a7w.py task <task_id> 续查) |
--stop-on-error | 一张失败就整体停 |
--person-blocklist | 外挂人物名单文件(一行一个名字,命中即拦) |
--allow-prompt-hits | 即使提示词命中闸门也出图(默认拦截;人物合规与未成年人不建议绕过) |
--report | 把本次证据(请求参数 / 任务原文 / 真实像素)写成 JSON,便于对账 |
cost —— 只算钱不出图
| 参数 | 说明 |
|---|---|
--count | 必填。要出几张 |
--resolution | 1K(默认)/ 2K / 4K |
--points-per-image | 覆盖单张单价(点)。2K/4K 必须给,见下 |
--budget | 预算上限(点),超了退出码 3 |
verify —— 复核已有图片的比例真伪
| 参数 | 说明 |
|---|---|
files | 要复核的图片文件(可多个) |
--ratio | 必填。请求比例,如 1:1 / 3:4 / 16:9 |
--ratio-tolerance | 比例容差,默认 0.03 |
models —— 列出在架应用与模型
打两个端点:GET https://api.a7w.cn/api/v1/apps(在架应用)与GET https://api.a7w.cn/api/v1/models(在架模型,按类型分)。本包用其中的 nano_banana。
模型名会变,别写死在脚本里。 出图模型的可选值也可以现查:
python3 scripts/a7w.py schema nano_banana
比例 preset(--preset)
| preset | 形态 | 设计比例 | 生成用的 aspect_ratio | 排版目标像素 | 上游 1K 实测像素 |
|---|---|---|---|---|---|
avatar | 头像 | 1:1 | 1:1 | 1024x1024 | 1024x1024(偏差 0.00%) |
cover34 | 社交封面 | 3:4 | 3:4 | 1080x1440 | 864x1184(偏差 2.70%) |
wide | 横版 | 16:9 | 16:9 | 1280x720 | 1344x768(偏差 1.56%) |
风格包(--style)
| 风格包 | 名称 | 适用场景 |
|---|---|---|
business | 商务精英 | 个人 IP 主页、名片、简历、团队介绍页 |
literary | 文艺清新 | 生活方式账号、书评影评、独立创作者主页 |
studiobw | 黑白棚拍 | 设计师、摄影师、品牌主理人的高级感形象 |
neon | 赛博霓虹 | 科技类账号、游戏与音乐人主页、潮流品牌形象 |
film | 复古胶片 | 怀旧叙事内容、播客封面、独立杂志与访谈栏目 |
guofeng | 国风雅致 | 传统文化内容、茶与香道、文博与文旅账号 |
六道本地硬闸门
闸门都是拦截 + 标红 + 退出码非 0,不是"提示一下"。因为出图是按次扣费的,
事后发现问题的代价是真金白银;而人物合规出问题的代价是账号。
执行顺序(前面拦下就不往后走):
--outdir 合法性(退出码 2)
→ 提示词闸门:人物合规 / 恶俗与违背物理 / 违禁词 / 照抄示例 / 占位符(退出码 3)
→ 成本上限(退出码 3)
→ --yes 确认(退出码 4)
→ 提交 → 轮询 → 下载 → 比例真伪(退出码 3)
1. 比例真伪 —— 读回真实像素,不信自报字段
不信接口返回里的任何比例字段,把图下载回来读文件头,用真实宽高算比例。
为什么必须这样:标题工坊上一版只信模型自报的 formula 字段做模板污染判定,
结果那个真该被判命的标题恰好漏判——闸门是假绿的。同一个错误在出图场景的形态是:
自报 aspect_ratio=3:4,真实像素却是 1024x1024。
而是先定总像素、再把每边向下对齐到 32 的倍数。所以 10 种比例里有 5 种拿不到
像素级精确比例——本包用到的三种里占两种:
| 请求 | 实测像素 | 实际比例 | 比例标签 | 偏差 |
|---|---|---|---|---|
3:4 | 864x1184 | 0.7297 | 27:37 | 2.70% |
16:9 | 1344x768 | 1.7500 | 7:4 | 1.56% |
1:1 | 1024x1024 | 1.0000 | 1:1 | 0.00% |
所以默认容差是 3%(容差内不算"假",但真实像素与偏差照样打印出来,不藏)。
要拿到像素级精确比例就加 --snap:按请求比例居中裁剪,裁完再读一次文件头复核,
只会把真正裁准的记成合格。实测 3:4 裁到 864x1152、16:9 裁到 1344x756,裁后偏差均为 0.00%。
原始文件保留不删(裁后版本文件名带 -snapped 后缀),两份都在,便于对账。
读像素这件事由独立模块 scripts/imgprobe.py 负责(PNG / JPEG / GIF / WebP 四种文件头解析,
只读、纯标准库)。做成独立模块而不是塞进 a7w.py,是因为 a7w.py 是所有包共用的客户端,
靠 SHA256 校验一致性,不许被单个包的私有需求污染。
2. 人物合规(本包特有,务必重视)
头像写真这个场景的特殊风险只有一个,但很硬:别人的脸。
| 拦什么 | 判定依据 |
|---|---|
| 政治人物 | 职衔与称谓特征词:主席、总统、总理、首相、总书记、领导人、议员、州长、政要、教皇、国王/女王… |
| 公众人物 / 明星 | 类别特征词:明星、名人、公众人物、艺人、演员、歌手、影帝、球星、网红、主播、爱豆、idol… |
| 指代结构 | 「像 ○○ 的脸」「○○ 同款脸」「撞脸」「换脸 / 人脸替换 / face swap」「○○ 主席」这类写法 |
| 外挂名单 | --person-blocklist <文件>,一行一个名字,命中即拦 |
| 未成年人 | 词(未成年/儿童/宝宝/小孩/孩子/少女/少年/校园风/校服/亲子照/萝莉…)与年龄数字 < 18(「12 岁」「15 周岁」)。本包一律不做未成年写真类生成,刻意偏严,「少年感」这类描述也会被拦 |
关于"具体姓名"的取舍(重要,见「已知取舍」):本包不内嵌任何在世真实个体的姓名。
把真人姓名写进一个公开分发的包里本身就是隐私风险,而且名单会迅速过期。
所以姓名拦截走三条路:类别词与称谓词(A)、指代结构(B)、外挂名单(C)。
需要按具体姓名拦截时用--person-blocklist。
3. 恶俗 / 违背物理
- 低俗:色情、裸露、半裸、走光、情趣内衣、内衣写真、湿身、艳照、挑逗、擦边、大尺度、制服诱惑
- 暴力违禁:血腥、暴力、尸体、自杀、枪械、毒品、管制刀具、恐怖袭击
- 解剖不可能:三只手、六指、双头、两张脸、多臂、断肢、断头、穿模、关节反向
- 物理不可能:水往高处流、反重力、影子方向不一致、无视透视
4. 成本上限
- 提交任何任务之前先算总价;超
--budget直接停,一个任务都不提交 - 每张提交前再核一次:前面真实扣费可能比预估高,超了就就地停
2K/4K没有实测单价 → 拒绝估算,退出码 3。宁可拒绝也不编一个数
(想估就给 --points-per-image)
5. 广告法违禁词
绝对化用语(最/第一/国家级/100%)、虚构权威背书、医疗功效、投资承诺、站外导流,
命中即拦。这一条对出图提示词同样适用——提示词里写了"全国第一的商务形象",
图上的字和物料大概率也是这个调性。
6. prompt_echo —— 照抄提示词示例
这条是从标题工坊的事故来的:提示词里写过的示例,哪怕明确标着"这是错的写法",
模型照样照抄——公众号那一轮最高分 89.0 的标题一字不差就是提示词里的示例,
最高分变成"抄标准答案",排序就废了。
出图场景更隐蔽:你不会一眼看出这张图和测试用例长得一样,而是"看起来挺正常",
直到发现整套写真其实是同一个模子。本包的方案由本地矩阵生成、不经过大模型,
所以照抄风险主要来自手改 plan.json 或直接喂 --prompt——闸门照样跑在前头。
判定:提示词里出现过的示例存成常量 PROMPT_SAMPLES,生成的出图提示词若
去标点后相等、或字符二元组 Jaccard ≥ 0.75、或示例二元组的覆盖度 ≥ 0.60,
三条任一命中就拦下。归一化后过短的(目标长度 < max(6, 示例长度/2))不比 —— 相对门槛,
不是写死的 12。
第三条是补漏:真人写真提示词动辄 60~150 字而示例只有 25 字,Jaccard 的分母是两份二元组的
并集,示例那一侧被长提示词摊薄得极狠,原样嵌进去也照样放行。本包 PROMPT_SAMPLES
与 sanjianke-image-factory 逐字相同,所以那边实测的窗口原样适用:
| 输入 | Jaccard | 覆盖度 | 结果 |
|---|---|---|---|
| 示例原样嵌入 + 补 9 个字(34 字) | 0.727 | 1.000 | 旧口径放行 ❌ → 新口径拦 ✓ |
| 示例原样嵌进 102 字的六段结构提示词 | 0.245 | 1.000 | 旧口径放行 ❌ → 新口径拦 ✓ |
覆盖度只看"示例被抄了多少",不看提示词有多长。
阈值 0.75 的标定依据(标题工坊实测 196 条):
| 输入 | 相似度 | 结果 |
|---|---|---|
| 逐字照抄示例 | 1.000 | 拦 |
| 只改标点 | 1.000 | 拦 |
| 加一个尾巴(实测 0.92) | 0.920 | 拦 |
| 同构照抄(换一个词) | 0.778 | 拦 |
| 真实业务提示词 | 0.042 | 放行 |
| 另一条业务提示词 | 0.000 | 放行 |
真实产出与示例之间 Jaccard 有 17 倍以上的安全距离,所以 0.75 既能兜住轻改写,又不会误伤。
覆盖度侧新测的余量:19 条真实/正常人像提示词里覆盖率最大 0.547,误伤 0 条。
登记在案的示例都是跨主题的(音箱、图标),与真实人像业务明显不搭。
已知取舍
这一节记录本包与同族包不同或刻意不做的地方,避免阅读时以为是遗漏。
| 取舍 | 说明 |
|---|---|
plan 不调用大模型 | 方案是矩阵式的(风格包 × 比例 × 变体),每一格由风格包与预设决定,不需要模型补全。好处是 styles / plan / cost 全部零网络零成本、可复现;代价是方案不会「因人而异」地自由发挥(要发挥就改 --subject 或自建风格包) |
--snap 默认 nonzero | 上游给 3:4 时天然带 2.70% 偏差,默认容差 3% 会让它落在容差内、一次都不裁,--snap 形同虚设。所以默认改成「偏差 > 0 就裁准」,想保持上游原始构图用 --snap-when overtolerance |
| 未成年人闸门刻意偏严 | 「少年感」「孩子气」这类用于成年人的描述也会被拦。写真场景下年龄误判代价太高,宁可让人改一次措辞 |
| 不内嵌真人姓名 | 见闸门二。个体名拦截走 --person-blocklist |
| 不做本地上传 | 上游没有上传接口,--photo-url 只接受公网 HTTP/HTTPS 地址 |
| 2K/4K 拒绝估算 | 没有实测单价就不给默认价,退出码 3 |
排错
| 现象 / 报错 | 原因 | 怎么办 |
|---|---|---|
鉴权失败(401) | Key 无效、过期或写错 | 到 https://api.a7w.cn/ 重新领取;确认没把 Bearer 重复写进环境变量 |
| 点数不足(HTTP 402) | 账号点数用完 | 到 https://api.a7w.cn/ 充值后重试 |
code: 0 但 HTTP 是 200 | 网关信封里 code == 1 才是成功,不是 0 | 看 body 里的 msg;脚本已按这个口径判断,别改成 code == 0 |
| 轮询一直读不到状态、最后超时 | status 在 data 顶层,不在 data.result 里(平台文档写错) | 脚本已按实测结构取;别看文档改回去 |
当前请求未命中可用计费规格 | model 与 resolution 组合不支持(如普通模型传 2K) | 普通 nano-banana 只支持 1K;要高清档换 nano-banana-2:official 之类 |
轮询一直 processing | 任务卡住了 | 已设 --poll-timeout(默认 600 秒)上限;超时会报出来并保留 task_id,可 python3 scripts/a7w.py task <task_id> 续查 |
读不出真实像素 | 下载被截断,或不是图片 | 删掉那条断点记录重出(--force),或检查网络 |
预估 N 点超过预算上限 | 超了 --budget | 提高预算、减少张数,或先 cost 试算 |
2K 档没有实测单价,拒绝凭猜估算 | 我们没有 2K/4K 的实测价 | 给 --points-per-image 指定单价,或先用 1K 出 |
输出目录 ... 在 Skill 包内(退出码 2) | --outdir 指到了包里的目录 | 换到包外(./out、%TEMP%\...)。包内放图片会让上传失败 |
提示词命中闸门 ... 已拦截,未提交任何任务 | 人物合规 / 未成年 / 恶俗 / 违禁词 / 照抄示例 / 占位符残留 | 改提示词后重跑;确实要带违禁词才加 --allow-prompt-hits(人物合规与未成年人不建议绕过) |
action=edit 需要参考图 URL | 图生图没给 --photo-url | 加 --photo-url;上游只接受公网 HTTP/HTTPS 地址,没有本地上传接口 |
| 重跑又扣了一次钱 | 提示词改了 → 断点 key 变了,被当成新的一项 | 这是设计如此(改了提示词就该重画)。想省钱就别改提示词,直接重跑即可跳过;重跑前先确认提示词没变,或先用 cost 核对预估花费 |
没有找到 API Key | 三种方式都没配 | --key / A7W_API_KEY / python3 scripts/a7w.py login --key sk-xxx |
| Windows 下中文乱码 | 控制台代码页不是 UTF-8 | 脚本已尝试把 stdout/stderr 掰到 UTF-8;仍乱码就 chcp 65001,或设 PYTHONIOENCODING=utf-8 |
收集排错信息时请附上:完整命令、plan 的输出、--report 产出的证据 JSON、原始报错文本。
不要在报错信息或截图里带上你的 API Key。
退出码(可直接用于流水线)
| 退出码 | 含义 |
|---|---|
0 | 全部成功且闸门全绿 |
2 | 调用失败 / 配置不合法(网络、鉴权、点数、模型名、--outdir 指到包内) |
3 | 闸门拦下:人物合规、未成年人、恶俗/违背物理、违禁词、照抄示例、比例不符、超预算、无实测单价 |
4 | 需要 --yes 确认(还没花钱,也没提交) |
5 | 达到 --max-seconds 上限中断(可续跑) |
130 | 用户中断(Ctrl+C) |
--json 输出契约(给流水线与 agent 消费,只在 --json 下生效):
- 成功:结果对象里多一个
"ok": true;顶层是数组时包成{"ok": true, "data": [...]} - 失败:stdout 输出一个 JSON 信封,形如
{"ok": false, "exit": 3, "error": {"kind": "gate", "message": "…"}}(exit 就是本次真实退出码),kind 取 gate / usage / budget / call / interrupt / internal。internal 是没预料到的异常(代码 bug)的兜底:此时 stdout 给信封、
完整 traceback 原样打到 stderr、退出码固定 1 —— 报 bug,不藏 bug
—— 只有在本次还没吐过任何 JSON 结果时才补这个信封;已经吐过结果时
(例如跑到一半才发现比例不合格),ok 就写在那个结果里,退出码不变
- 人读文案照旧走 stderr;退出码语义一个都不变;非
--json模式输出与以前完全一致 --json写在子命令前面或后面都可以
成本口径
| 项 | 实测 |
|---|---|
nano_banana 1K 出图 | 24 点/张 = 0.24 元 |
| 充值比例 | 1 元 = 100 点 |
| 提交时冻结 | 实测 frozen_points = 31.2(预冻结,不是最终扣费) |
| 完成后结算 | usage.points_cost = 24 |
| 失败 | 全额退回 |
| 2K / 4K | 无实测单价 → 拒绝估算(退出码 3),除非显式给 --points-per-image |
只信 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-portrait-studio/
├── SKILL.md 本文件
├── README.md 给人看的说明
├── LICENSE.md MIT,署名三剪客
├── references/
│ ├── style-packs.md 风格包、提示词写法、合规红线、自建风格包
│ ├── platform-specs.md 各展示位尺寸与安全区、上游 32 对齐实测、裁剪口径
│ └── cost-and-troubleshooting.md 计费口径、实测数据、断点续跑与排错
└── scripts/
├── a7w.py api.a7w.cn 零依赖客户端(**逐字节等于规范版,本包不改它**)
├── imgprobe.py 图片头探针:读真实像素 PNG/JPEG/GIF/WebP(只读,纯标准库)
└── run.py styles / plan / gen / cost / models / verify
端点速查
算力集市(api.a7w.cn)的出图是两步异步任务(下面每一行的域名都来自算力集市 api.a7w.cn):
| 用途 | 方法与路径 |
|---|---|
| 提交出图任务(算力集市 api.a7w.cn) | POST https://api.a7w.cn/api/v1/apps/nano_banana/submit |
| 查任务结果(本包用它) | GET https://api.a7w.cn/api/v1/tasks/<task_id> |
| 查任务结果(应用级,备用;同属算力集市 nano_banana) | POST https://api.a7w.cn/api/v1/apps/nano_banana/query |
| 看某应用的接口与参数 | 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 |
没有 /generate 这个端点。「文生图」是 submit 的 action=generate 参数,
「图生图」是 action=edit 参数 + image_urls,都不是独立的 api 路径——
我们之前凭记忆写错过,被实测纠正,这里留个记号。
submit 的参数名(用 python3 scripts/a7w.py schema nano_banana 实查,别猜):prompt / action(generate|edit) / resolution(1K|2K|4K) / aspect_ratio / image_urls / model / callback_url
联系我们
- 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
- 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
- 更多 AI 插件与接口:AI 插件市场。
相关链接
- 算力集市 api.a7w.cn(注册领 Key):https://api.a7w.cn/
- 风格包与提示词写法:
references/style-packs.md - 计费口径与排错:
references/cost-and-troubleshooting.md
免责声明:本包内置的人物合规词表、恶俗词表与违禁词表都是启发式自检工具,
来自公开经验整理,不构成法律意见,也不代表任何平台的官方审核标准。
**它拦的是「使用者把明显不该做的要求写进了提示词」这一种最可控的情形,
不能替代肖像权判断**:你有没有权利使用某张人像照、生成结果能否用于商业投放,
由使用者自行确认并承担全部责任。
涉及真人肖像、品牌标识、医疗健康、金融等高风险内容必须人工复核后再发布。
费用提示:出图按次扣费,--report产出的证据文件里逐张记了真实扣费
(usage.points_cost),请以它为准对账。本包不做代付,也不内嵌任何密钥。