gpt-image-playground-agent

name	gpt-image-playground-agent
description	当用户需要通过已部署的 GPT Image Playground 生成、编辑、批量生成或诊断图片接口时使用；必须优先运行本 Skill 内置 scripts/generate-image.mjs、edit-image.mjs、batch-images.mjs 或 probe-upstream-image.mjs，而不是临时编写 API 调用脚本。

GPT Image Playground Agent

通过用户已部署的 GPT Image Playground 生成、编辑、批量处理或诊断图片接口。不要假设服务一定在本机；不要模拟网页表单；优先运行本 Skill 内置脚本，让脚本处理 Agent API 契约、capabilities、幂等键、路由选择和产物 URL。

脚本优先规则

• 生成单张或少量图片：优先运行 scripts/generate-image.mjs。
• 编辑图片：优先运行 scripts/edit-image.mjs。
• 批量 generate/edit：优先运行 scripts/batch-images.mjs，用 JSONL 输入和 append-only manifest 管理续跑。
• 诊断上游图片接口：优先运行 scripts/probe-upstream-image.mjs。
• 不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现这些脚本已经覆盖的 API 调用。
• 只有在内置脚本缺少用户明确需要的能力时，才修改或扩展 scripts/ 内的预置脚本，并同步补测试；不要在仓库外留下 ad hoc 调用脚本。
• 先用 dry-run 或 --contract-check 检查请求、路由和鉴权；只有用户明确允许真实计费时才加 --allow-billable。

路由规则

• 先读取 GET /api/agent/capabilities 的 routing_rules，按机器可读规则选择端点。
• edit 且 max(width,height)>2048 时，默认优先使用页面端 POST /api/images form-data SSE 路径；如果页面流式不可用或失败，先诊断结构化错误，再显式回退到 Agent edit。
• 复杂 UI 批量出图优先使用页面端 POST /api/images SSE，并记录切换原因、失败清单和续跑锚点。
• 长图恢复或需要续跑锚点的生产请求优先使用页面端 POST /api/images SSE，保留局部进度和缺最终图诊断。
• 普通小图单次文生图使用 /api/agent/images/generate；max_edge>2048 的单次文生图默认优先走页面端 /api/images SSE，流式失败后先诊断，再显式选择 Agent JSON 或 job 路径，不自动回退。
• 同一个已进入终态 failed 的 Idempotency-Key 只会回放失败；重新尝试必须先诊断原因，再创建新的业务操作和新的 key。

执行流程

1. 先按任务类型选择内置脚本，不要从零写 API 调用代码。
2. 定位服务基础地址。优先使用用户明确提供的 URL；其次使用 GPT_IMAGE_PLAYGROUND_URL；都没有时尝试默认地址 http://localhost:4783。
3. 让脚本请求 GET /api/agent/capabilities。如果默认地址不可达、404、不是 JSON 或不是 Agent capabilities 响应，向用户询问实际部署地址、端口、域名和是否需要鉴权。
4. 读取 capabilities 中的认证方式、模型、模型级限制、routing_rules、Agent 流式边界、页面 SSE 鉴权、后端 runtime enablement、状态后端和端点路径；不要硬编码假设部署方式。
5. 为每个业务操作生成稳定的 Idempotency-Key。网络中断、运行中轮询或非终态重试复用原 key；同一 key 已进入 failed 终态后不再用于触发新执行，必须先诊断原因，再创建新的业务操作和新的 key。
6. 文生图使用 POST /api/agent/images/generate，请求体为 JSON。该 Agent 端点对外始终返回最终 AgentImageResponse JSON；如 capabilities 声明 agent_streaming.upstream_sse.supported=true，可通过 image_backend、stream_mode、streaming_strategy、partial_images 控制内部上游 SSE 消费。
7. 图片编辑使用 POST /api/agent/images/edit，请求体为 multipart/form-data，源图字段必须使用 image_0..image_9，类似 image_10、image_01 或 image_foo 的字段会被显式拒绝。该 Agent 端点同样是非流式端点；上游 SSE 字段按 agent_streaming.upstream_sse.request_fields_by_mode.edit 发送，不要给 edit 传 image_backend。
8. 默认使用 response_mode: "path"，只在用户明确需要图片内联数据时使用 base64 或 both。
9. 不要把页面端 POST /api/images 当成普通 Agent JSON 路径。它是页面表单和 SSE 路径，capabilities 会以 agent_streaming.page_sse 单独声明；仅在 routing_rules 命中高分辨率 edit、大图单次文生图、复杂 UI 批量、长图恢复或明确诊断后切换。
10. 读取 agent_jobs。job 路径只在显式选择时使用；max_edge>2048 的单次文生图默认优先走页面端 /api/images SSE。
11. 处理失败时读取结构化 error.code、error.retryable、error.diagnostics 和 Retry-After。仅当 retryable=true 时等待后重试。
12. 返回结果时优先给出 content_url、metadata_url、absolute_content_url、absolute_metadata_url、产物 ID、尺寸、格式和是否命中幂等缓存。

鉴权

Agent JSON、Agent edit、job 和 artifact 端点的鉴权以 auth.schemes 为准。如果服务端配置了 AGENT_API_TOKEN，发送：

Authorization: Bearer <token>

此时 Agent 端点只接受 Bearer token，不会回退到访问码哈希。如果未配置 AGENT_API_TOKEN 但配置了页面访问码 APP_PASSWORD，Agent 端点发送 X-App-Password-Hash。下载或删除产物时必须复用 capabilities 声明的同一 Agent 鉴权方式。

页面端 /api/images SSE 是独立页面契约，读取 agent_streaming.page_sse.auth。当该字段声明 required=true 时，必须在 form-data 中发送 passwordHash；脚本侧对应环境变量是 GPT_IMAGE_APP_PASSWORD_HASH。即使 auth.schemes 只返回 bearer，混合配置下 page SSE 仍可能需要这个表单访问码哈希。页面 SSE 还会把同一业务 key 写入 form-data clientRequestId，长度不得超过 agent_streaming.page_sse.client_request_id.max_length。

调用约束

• 不要把 API Key、token 或访问码写入源码、文档示例、日志或测试快照。
• Skill 必须保持自包含和可迁移：脚本、示例和说明不得写入本机绝对路径或仓库绝对路径；运行脚本时以当前已安装 Skill 目录为根解析 scripts/，不要依赖某台机器上的 checkout 位置。
• Skill 必须兼容 Windows、Linux 和 macOS：脚本只用 Node.js 20+ 与跨平台 node: 标准库；文档示例用 node "<skill-root>/scripts/..."，不依赖 bash、sh、chmod、可执行位、POSIX inline env 或反斜杠续行。
• 不要把 localhost:4783 当作唯一部署位置；它只是无明确地址时的探测默认值。
• 不要在模型上下文中展开大体积 base64，除非用户明确要求。
• 不要把 error.message 当成唯一判断依据；稳定分支以 error.code 和 HTTP 状态为准。
• 不要在没有 Idempotency-Key 的情况下调用生成或编辑接口。
• 不要对同一个已进入终态 failed 的 Idempotency-Key 继续重试。终态失败回放会返回 retryable=false；需要重新尝试时，先确认失败原因，再创建新的业务操作和新的 Idempotency-Key。
• 不要把 agent_streaming.page_sse.supported=true 解读为 /api/agent/images/generate 会对客户端返回 SSE；Agent generate/edit 对外仍是最终 JSON。agent_streaming.upstream_sse 仅表示服务端内部可消费上游 SSE 并保存最终 artifact。
• 不要调用 job endpoints，除非 capabilities 明确返回 agent_jobs.supported=true 且 mode=job_polling。
• 不要把一次高分辨率、高质量长耗时失败归纳为全局不可用。优先查看 error.diagnostics.upstream_status、upstream_event_type、partial_image_count、transport_error、selected_channel_id、channel_cooldown_scope 和 retry_after_seconds。
• 不要在 error.retryable=false 时依据历史 retry_after_seconds 继续重试同一个 key；终态失败需要新业务操作和新 key。

Job Polling

当 agent_jobs.supported=true 时，显式 job 路径可使用：

1. POST /api/agent/jobs/images/generate 创建 job，仍必须提供 Idempotency-Key。
2. GET /api/agent/jobs/{id} 轮询状态。
3. GET /api/agent/jobs/{id}/result 在 state=succeeded 后读取标准 AgentImageResponse。

GET /result 在 job 运行中会返回 request_in_progress 和 Retry-After；不存在返回 job_not_found；过期返回 job_expired。同一业务操作重试创建 job 时复用原 Idempotency-Key，服务会返回同一个 job。

当前 job polling 是同一服务实例内的后台任务，结果和错误写入 Agent 状态后端；它不是跨实例持久队列。若服务进程在 job 结束前重启，客户端应按状态和错误码继续轮询或重新创建同一 Idempotency-Key 的 job。若 job 已进入 failed 终态，GET /result 和状态摘要都会返回 retryable=false，并保留 code、message、upstream_status 和 diagnostics 用于定位原因，但同一个 key 不会触发新执行。需要重新尝试时，先确认失败原因，再以新的业务操作和新的 Idempotency-Key 创建 job。默认大图单次文生图已经切到页面端 /api/images SSE，job 不是默认路径。

可用脚本

以下脚本都位于当前 Skill 目录的 scripts/ 下。不要硬编码本机安装路径；由运行环境按当前 SKILL.md 所在目录解析脚本路径。

• scripts/generate-image.mjs：JSON 文生图调用。默认 dry-run，不消耗额度；必须添加 --allow-billable 才会真实生图。
• scripts/edit-image.mjs：multipart 编辑调用。默认 dry-run，不消耗额度；必须添加 --allow-billable 才会真实编辑。
• scripts/batch-images.mjs：JSONL 批量 generate/edit 调用。默认 dry-run，不消耗额度；必须添加 --allow-billable 才会真实逐行执行，支持 append-only manifest、--resume、--ordered-prefix 和 --dimension-check。
• scripts/probe-upstream-image.mjs：直接探测上游图片接口连通性。默认只检查 DNS、TLS 和 /models，必须添加 --allow-billable 才会真实调用 /images/generations。

生成和编辑脚本的 dry-run 输出会包含 routing_guidance，用于在真实计费前检查当前请求应走 Agent JSON、页面 SSE，或在页面流式失败后先诊断再手动选定后续路径。 所有脚本在 dry-run 或真实请求前都会校验尺寸参数。gpt-image-2 支持 auto 或 WIDTHxHEIGHT，且宽高必须为 16 的倍数、单边不超过 3840、宽高比不超过 3:1。最低分辨率按总像素 min_pixels=655360 判断，最高分辨率同时受 max_pixels=8294400 和 max_edge=3840 约束。非 gpt-image-2 模型只接受 auto、1024x1024、1536x1024 或 1024x1536。

如果当前上下文位于仓库根目录，管理员侧优先使用顶层命令：

• npm run status：只读查看 git、Space 目标、Agent API、Skill 入口和独立真实图片上游 smoke 配置摘要；会自动读取 .env.real-smoke.local，不输出 URL 或 API Key。
• npm run doctor：统一诊断本机与 HF Space 配置，不写 Secret。
• npm run verify：运行提交前基线；需要真实 PostgreSQL gate 时加 -- --postgres。
• npm run deploy:local：重建本地 Docker 服务并探测真实 HTTP 端点；加 -- --memory 会断言 memory/indexeddb overlay 生效。
• npm run deploy:space：部署干净 git HEAD 到固定 Space，并做只读公网验证。
• npm run agent:doctor：执行非计费分层诊断，覆盖 capabilities、Agent contract、runtime backend、state backend 和 Responses/GPT2Image readiness；真实 1K/2K smoke 必须显式加 -- --allow-billable。

生成脚本常用参数：

node "<skill-root>/scripts/generate-image.mjs" --size 2048x2048 --quality high --response-mode path --idempotency-key stable-operation-key "a product photo of a ceramic mug"

启用 Agent 内部上游 SSE 时，必须显式传策略字段；脚本仍只输出最终 JSON：

node "<skill-root>/scripts/generate-image.mjs" --allow-billable --image-backend images-api --stream-mode auto --streaming-strategy newapi-keepalive-sse --partial-images 2 --size 3840x2160 --quality high "a product photo of a ceramic mug"

真实生图必须显式开启：

node "<skill-root>/scripts/generate-image.mjs" --allow-billable --timeout-ms 420000 --size 2048x2048 "a product photo of a ceramic mug"

生成脚本会对 max_edge>2048 的单次文生图默认优先走页面端 /api/images SSE；如果 capabilities 未声明 agent_streaming.page_sse.supported=true，脚本会显式失败，不会静默降级到 Agent JSON。如果页面流式失败，脚本会返回结构化失败结果，先诊断再决定是否用 --agent 或 --job 重新执行，不会自动发起第二次请求。编辑脚本对高分辨率 edit 也采用同样口径：默认页面流式，有问题再显式回退到 Agent edit 诊断或执行。也可以用 --page-sse 强制页面流式，或用 --agent 强制 Agent generate/edit 最终 JSON，--job 仍可显式选择 generate job 路径。显式传 --streaming-strategy off 或 --stream-mode non_stream 时，大图请求保持 Agent JSON 非流式路径，用于和页面 SSE 做诊断对照。上游流式字段优先读取 agent_streaming.upstream_sse.request_fields_by_mode：generate 支持 --image-backend、--stream-mode、--streaming-strategy、--partial-images；edit 只支持 --stream-mode、--streaming-strategy、--partial-images。不发送时使用服务端 capabilities 声明的默认值。

批量脚本 JSONL 每行是一个 generate 或 edit 任务。示例：

{"id":"hero-01","mode":"generate","prompt":"a product photo of a ceramic mug","size":"1024x1024","response_mode":"path"}
{"id":"edit-01","mode":"edit","prompt":"replace the background","image_path":"./source.png","size":"1024x1024","response_mode":"path"}

默认 dry-run 只解析 JSONL、生成稳定幂等键并输出计划，不请求服务：

node "<skill-root>/scripts/batch-images.mjs" --input tasks.jsonl --ordered-prefix product-set

真实批量执行必须显式允许计费：

node "<skill-root>/scripts/batch-images.mjs" --allow-billable --input tasks.jsonl --manifest runs/product-set.manifest.jsonl --resume --dimension-check --max-attempts 2 --max-consecutive-failures 3

--manifest 使用 JSONL append-only 记录每条任务的 index、id、idempotency_key、attempt、status、响应或错误；--resume 会读取已成功记录并跳过同一 id 或 idempotency_key。--dimension-check 会读取响应里的 b64_json 或同 origin content_url，校验 PNG/JPEG/WebP 尺寸是否等于任务 size。--max-attempts 会为第二次及以后尝试追加新的 attempt 级 idempotency key，避免复用终态失败 key；--max-consecutive-failures 会在连续失败达到阈值后跳过后续任务并输出 failure_summary 与 resume_fix_list。任务级 sse_log_path 会把页面 SSE 原始事件按 JSONL 追加保存，便于区分上游未给终图和解析/断流问题。

批量 JSONL 字段按模式区分：background 只适用于 generate；image_path、image_paths、mask_path 只适用于 edit。output_format、format、output_compression、moderation、image_backend、responsesModel/gptModel/gpt_model、thinking、promptOptimization/prompt_optimization、force_web/forceWeb 可用于页面 SSE 路径；edit 任务使用这些高级字段会显式走 /api/images，因为 Agent JSON edit 不接收它们。responsesModel 必须同时设置 image_backend=responses-image-generation 或兼容值 responses。PNG 搭配 output_compression 会在 dry-run 标记 normalization，真实请求不会发送压缩字段。page_sse、complex_ui、long_image、resume_or_recover 必须是 JSON 布尔值，transport 目前只接受 page_sse。脚本会在 dry-run 阶段显式拒绝跨模式字段、未知字段和无效路由控制字段。

编辑脚本支持 --model、--size、--quality、--response-mode、--stream-mode、--streaming-strategy、--partial-images、--timeout-ms、--idempotency-key、--page-sse、--agent、--dry-run 和 --allow-billable。

直连上游诊断：

node "<skill-root>/scripts/probe-upstream-image.mjs" --base-url https://api.openai.com/v1

调用前按当前系统和 shell 设置 OPENAI_API_KEY 或 GPT_IMAGE_UPSTREAM_API_KEY，不要把 key 写进命令历史或文档。

诊断脚本只输出状态、耗时、脱敏错误摘要、白名单响应头和 base64 长度，不输出 API key 或完整图片数据。

上游探针脚本支持 --base-url、--model、--prompt、--size、--quality、--format、--timeout-ms 和 --allow-billable。默认读取 GPT_IMAGE_UPSTREAM_BASE_URL 或 OPENAI_API_BASE_URL，API Key 读取 GPT_IMAGE_UPSTREAM_API_KEY 或 OPENAI_API_KEY。上游 base URL 同样必须是无凭据、无查询参数、无片段的 http/https 绝对 URL。

脚本读取以下环境变量：

• GPT_IMAGE_PLAYGROUND_URL：服务基础地址，可指向本机、局域网、云服务器或域名；脚本未设置时默认尝试 http://localhost:4783。
• GPT_IMAGE_AGENT_TOKEN：Bearer token。
• GPT_IMAGE_APP_PASSWORD_HASH：使用 APP_PASSWORD 访问码部署时，Agent 端点发送为 X-App-Password-Hash，页面 SSE 发送为 form-data passwordHash。
• GPT_IMAGE_AGENT_IDEMPOTENCY_KEY：跨脚本进程恢复同一操作时复用的幂等键。
• GPT_IMAGE_AGENT_MAX_ATTEMPTS：最大尝试次数，默认 3。
• GPT_IMAGE_AGENT_CONTRACT_CHECK=1：只检查 capabilities 和错误契约，不触发真实生图或编辑。

GPT_IMAGE_PLAYGROUND_URL 必须是无凭据、无查询参数、无片段的 http/https 绝对 base URL。不要把 token、访问码或其他 Secret 放进 URL。生成脚本轮询 job result 时只会携带鉴权头访问同 origin URL，避免异常服务返回外部 result_url 后泄露 Bearer token 或访问码哈希。

脚本会把服务返回的相对产物路径补充为绝对 URL，页面 SSE 的相对 path 会补充 absolute_path，适合调用 Hugging Face Space、云服务器或自定义域名上的公网实例。

参考

需要字段结构、响应示例或错误码列表时，读取 references/api.md。