# apizt 批量图片编辑

Python 3.10+，仅标准库。MIT。固定使用 `POST https://api.apizt.com/v1/images/edits`，单张 PNG 输入与 PNG base64 输出，串行执行。输入最多 10 MiB、最多 100 行；这些是脚本限制，不是官方接口上限。

## 1. 准备文件

下载 `batch-image-editing.py` 和 `batch-image-jobs.csv`。准备自己有权使用的 PNG，放入 `input-images/`；修改 CSV 中的 `image` 和 `prompt`。示例的两张商品图是待替换文件名，没有附带已验收的商品成品。

`id,image,prompt` 三列顺序固定。ID 唯一，使用英文字母、数字、下划线或短横线。图片路径相对 `--input-root`，不支持上级目录或远程 URL。修改同一任务的原图、提示词或参数后，脚本会停止，防止把新任务混入旧账单；保留原任务记录，另起明确的新 ID。

## 2. 离线预览

```bash
python3 batch-image-editing.py --jobs batch-image-jobs.csv --input-root input-images
```

离线模式读取 CSV 和输入 PNG，检查路径、签名与任务指纹；不读取环境密钥，不联网，不创建状态文件。现有输出目录中的 manifest 会参与重复任务检查。

## 3. 一张小样

在本地安全设置环境变量 `tokenba_API_KEY`。先在模型广场核对自己的令牌可用模型、图片编辑接口、参数和价格，再执行：

```bash
python3 batch-image-editing.py --jobs batch-image-jobs.csv --input-root input-images --out batch-output --run --max-requests 1
```

会发出最多一次计费请求。原图和提示词随请求上传；密钥只发送给固定 apizt HTTPS 接口，不允许请求重定向。默认 `model=gpt-image-2`、`n=1`、`size=1024x1024`、`quality=low`。可选 `--size` 与 `--quality` 不代表通道一定透传；已有实测曾出现请求 1024×1024、实收 1254×1254，必须检查实际结果。

## 4. 验收后继续

```bash
python3 batch-image-editing.py --jobs batch-image-jobs.csv --input-root input-images --out batch-output --run --max-requests 10
python3 -m json.tool batch-output/manifest.json
```

保留同一个 `batch-output`。成功任务按 manifest 与文件摘要校验后跳过，未提交任务继续，超时或异常任务不会自动重发。每次运行的上限为 1–100，默认 1；没有并发、自动退避重试或后台循环。

`succeeded` 仅表示 PNG 签名、IHDR 尺寸和落盘检查通过，不等于完整图片解码、主体一致性、中文准确性或视觉验收通过。用 `image-acceptance-checklist.csv` 记录人工验收。manifest 的 `billed_usd=null`；按控制台实扣独立核对费用，usage 不能直接当作账单。

## 5. 超时与中断

请求前先持久化 `indeterminate/request_in_flight`。网络超时、HTTP 错误、响应格式异常都会保留未确定状态并停止本轮；下一次运行默认跳过该任务。不能据 HTTP 错误或客户端等待超时判断“未计费”。

结果摘要的 `indeterminate_jobs` 大于 0 时，命令以退出码 1 提醒检查 manifest；它不代表远程请求未处理，也不代表没有费用。退出码 0 也不等于全部任务、画面验收或账单核对完成。

收到可解码结果后，脚本先保存只含图片和数值 usage 的私有缓存，再保存 PNG 与状态。若中断发生在落盘期间，下一次运行优先从缓存恢复，不再 POST。缓存不保留完整 API 正文、提示词、URL 或返回错误消息。URL 返回不下载：先核对通道的 base64 返回格式，避免把错误页当成图片。

确认控制台与已有结果都没有可恢复内容，接受再次请求可能产生费用后，才显式重发指定任务：

```bash
python3 batch-image-editing.py --jobs batch-image-jobs.csv --input-root input-images --out batch-output --run --resume-job sku-blue --acknowledge-new-charge --max-requests 1
```

不要删除 manifest 来“重新开始”。成功文件缺失或被修改时，脚本要求恢复文件，不自动再次计费。输出目录的 `.batch.lock` 防止两个脚本同时提交；异常强制退出可能留下锁。先确认对应进程已停止、检查 manifest，再移除锁文件；保持任务记录完整。

## 6. 本地记录与限制

本地输出文件权限为 0600，新建输出目录为 0700。manifest 保留任务 ID、输入/提示词摘要、参数、状态、尝试次数、结果摘要、尺寸和数值 usage，不保留提示词原文与密钥。CSV 仍是本地原始任务材料，自己妥善保管。

脚本不会自动验证 SKU、Logo、标签、二维码、颜色或平台上架规则，也不是 OpenAI Batch API。不要将本地顺序处理当作批量折扣。只有一个真实的既有背景编辑样例，尚未发起本批次商品、海报或批量付费实测。