{"openapi":"3.0.3","info":{"title":"图盾·工坊 API","version":"1.0.0","description":"电商商品图生成 API. 用 API Key (Bearer) 鉴权, 同步生图, 返回 24h 公网签名 URL.\n\n详细 Prompt 写作指南见 [文档](https://image.bjaydmy.com/docs/api-v1)."},"servers":[{"url":"https://image.bjaydmy.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"tdgz_live_xxx"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string","description":"错误码, 见文档"},"message":{"type":"string"},"id":{"type":"string","description":"job id, 若已分配"}}},"GenerationRequest":{"type":"object","required":["workflow"],"properties":{"image_url":{"type":"string","description":"原图(单图): 公网 https URL, 或 base64 data URL (data:image/png;base64,...)。与 image_urls 二选一, ≤ 20MB"},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":6,"description":"多图参考(最多6张, 同一商品多角度/多色)。仅 selling-points / detail-images 两个展示类 workflow 支持(白底图/促销图用单张 image_url)。仅 laozhang-default 模型; gemini-2.5-flash 不支持。与 image_url 二选一"},"workflow":{"type":"string","enum":["main-image","selling-points","promotion-images","detail-images"],"description":"工作流类型"},"prompt":{"type":"string","maxLength":200,"description":"整体 prompt 方向, 与 prompts 互斥"},"prompts":{"type":"array","items":{"type":"string","maxLength":200},"minItems":1,"maxItems":6,"description":"每张图独立 prompt, 仅 selling-points / detail-images, 与 prompt 互斥, 数组长度锁定出图数"},"negative_prompt":{"type":"string","maxLength":200,"description":"反向约束, 例: 不要文字水印"},"raw":{"type":"boolean","description":"true 时跳过框架模板注入, agent 100% 控制 prompt"},"model":{"type":"string","enum":["gemini-2.5-flash","laozhang-default"],"description":"可选模型, 不传走 workflow 默认"},"size":{"type":"string","enum":["1280x1280","1536x2048","1920x1920"]},"n":{"type":"integer","minimum":1,"maximum":6,"description":"出图数, 仅多图 workflow, 与 prompts 互斥"},"platform_profile":{"type":"string","enum":["taobao","tmall","jd","pdd"],"description":"仅 detail-images: 平台规格 (淘宝/天猫/京东/拼多多)"},"callback_url":{"type":"string","description":"仅异步接口 POST /jobs 生效: job 终态后回调此 https URL (POST job 状态), SSRF 防护 + 失败重试"},"callback_secret":{"type":"string","description":"仅异步接口: 回调 body 用它做 HMAC-SHA256, 放 X-Tdgz-Signature 头供验真伪"}}},"GenerationResponse":{"type":"object","properties":{"id":{"type":"string","description":"job id"},"created":{"type":"integer","description":"unix 秒"},"credits_used":{"type":"integer","description":"本次实际扣点数 = 生成图数"},"credits_remaining":{"type":"integer","description":"账户剩余余额近似值"},"workflow":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"签名 URL, 24h 内有效"},"expires_at":{"type":"integer","description":"unix 秒"}}}}}},"JobSubmitResponse":{"type":"object","properties":{"id":{"type":"string","description":"job id"},"status":{"type":"string","enum":["queued"],"description":"提交时恒为 queued"},"status_url":{"type":"string","description":"查询路径 /api/v1/jobs/{id}"}}},"JobStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"workflow":{"type":"string"},"created":{"type":"integer","description":"unix 秒"},"credits_used":{"type":"integer","description":"succeeded 时出现 = 生成图数"},"data":{"type":"array","description":"succeeded 时出现","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"签名 URL, 24h 内有效"},"expires_at":{"type":"integer","description":"unix 秒"}}}},"error":{"type":"object","description":"failed / canceled 时出现","properties":{"code":{"type":"string"}}}}},"Account":{"type":"object","properties":{"user_id":{"type":"string"},"credits_remaining":{"type":"integer"},"license_status":{"type":"string","enum":["active","trial","expired"]},"key_label":{"type":"string"},"month_to_date":{"type":"object","properties":{"api_calls":{"type":"integer"},"credits_used":{"type":"integer"}}}}},"Models":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"supported_sizes":{"type":"array","items":{"type":"string"}}}}},"platform_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"applies_to":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/api/v1/images/generations":{"post":{"summary":"同步生图","description":"传公网图片 URL + workflow, 30~120s 内同步返回签名 URL 数组.\n\n响应必带 X-RateLimit-Limit / Remaining / Reset-At 头.\n\n可选 Idempotency-Key 头: 同 key + 同 body 返缓存, 同 key + 不同 body 返 409.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"幂等键, 24h 内同 key 同 body 不重复扣费"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}}},"responses":{"200":{"description":"生成成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResponse"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API Key 缺失/无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"余额不足 (INSUFFICIENT_CREDIT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Trial 限制或内容审核拒绝","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key 冲突 (同 key 但 body 不同)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"限流, 见 Retry-After 头","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"上游模型错","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"生成超时 (>120s), 积分自动退还","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs":{"post":{"summary":"异步生图 (提交)","description":"与同步接口同 body, 但立即返 202 + job_id, 不阻塞连接。适合长任务/高吞吐: 提交后用 GET /api/v1/jobs/{id} 轮询。\n\n支持 Idempotency-Key: 同 key 同 body 返同 job。","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"幂等键, 同 key 同 body 返同 job, 不重复扣费"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}}},"responses":{"202":{"description":"已受理","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobSubmitResponse"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API Key 缺失/无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Trial 限制或内容审核拒绝","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key 冲突","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"限流, 见 Retry-After 头","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}":{"get":{"summary":"异步生图 (查询)","description":"查 job 状态。status: queued / processing / succeeded / failed / canceled。succeeded 时带 data[] 签名 URL。只能查自己 key 提交的 job。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"POST /jobs 返回的 job id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"401":{"description":"API Key 缺失/无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"job 不存在或非本人","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account":{"get":{"summary":"账户信息","description":"余额 / 会员状态 / 当月统计.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"API Key 缺失/无效"}}}},"/api/v1/models":{"get":{"summary":"列可选模型 / 平台规格","description":"公开端点, 无鉴权.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Models"}}}}}}},"/api/v1/files/{token}":{"get":{"summary":"下载生成结果","description":"签名 URL, 24h 过期. 拿到链接就能看 (无 owner 校验).","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"图片内容","content":{"image/png":{},"image/jpeg":{},"image/webp":{}}},"404":{"description":"Token 无效 / 过期 / 文件不存在 (统一 404 防信息泄露)"}}}},"/api/v1/mcp":{"post":{"summary":"MCP server (streamable HTTP transport)","description":"供 MCP 客户端 (Claude Desktop / Cherry Studio / Continue) 配置.\n\n协议: JSON-RPC 2.0 over HTTP. 工具列表见 tools/list method.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"JSON-RPC 2.0 request"}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object"}}}},"204":{"description":"notifications/* 不需要响应"},"401":{"description":"API Key 缺失/无效"}}}},"/api/v1/whoami":{"get":{"summary":"诊断: 当前 API Key 对应的账户","description":"agent 集成时确认 Key 接通用.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"API Key 缺失/无效"}}}}}}