{"openapi":"3.1.0","info":{"title":"PromptCraft Developer API","version":"1.0.0","description":"PromptCraft 提示词生成 REST API，支持 4 工坊 / 全目标模型。\n\n## 版本政策（P2-18）\n- 当前稳定版本：v1（路径前缀 `/api/v1/`）\n- 向后兼容的变更（新增字段/端点）不升版本\n- 破坏性变更走 v2，v1 至少维护 6 个月（届时响应头带 `Sunset` 和 `Deprecation`）\n- 弃用端点会在响应中返回 `Deprecation: true` 和 `Sunset: <date>` 头"},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pck_live_xxx"}},"schemas":{"GenerateRequest":{"type":"object","required":["workshop","model","params"],"properties":{"workshop":{"type":"string","enum":["image","text","audio","video"]},"model":{"type":"string","example":"midjourney"},"params":{"type":"object"},"options":{"type":"object","properties":{"locale":{"type":"string"},"adaptAll":{"type":"boolean"}}}}},"GenerateResponse":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"negativeText":{"type":"string","nullable":true},"modelParams":{"type":"object"},"segments":{"type":"array"},"length":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}},"targetModel":{"type":"string"},"adaptedTexts":{"type":"array","nullable":true}}},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}},"security":[{"bearerAuth":[]}],"x-codeSamples":{"curl":"curl -X POST https://your-app.vercel.app/api/v1/prompts/generate \\\n  -H \"Authorization: Bearer pck_live_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"workshop\":\"image\",\"model\":\"midjourney\",\"params\":{\"subject\":{\"age\":\"adult\"}}}'","fetch":"const res = await fetch('https://your-app.vercel.app/api/v1/prompts/generate', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer pck_live_xxx',\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ workshop: 'image', model: 'midjourney', params: {...} }),\n})\nconst data = await res.json()","python":"import requests\nres = requests.post(\n    'https://your-app.vercel.app/api/v1/prompts/generate',\n    headers={'Authorization': 'Bearer pck_live_xxx', 'Content-Type': 'application/json'},\n    json={'workshop': 'image', 'model': 'midjourney', 'params': {...}},\n)\ndata = res.json()"},"paths":{"/prompts/generate":{"post":{"summary":"生成提示词","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"200":{"description":"生成成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"参数非法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"未认证","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"限流","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/prompts/adapt":{"post":{"summary":"切换目标模型","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"成功"},"400":{"description":"参数非法"},"401":{"description":"未认证"}}}},"/prompts/validate":{"post":{"summary":"仅校验参数","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"校验结果"},"400":{"description":"参数非法"},"401":{"description":"未认证"}}}},"/templates":{"get":{"summary":"列出公开模板","parameters":[{"name":"workshop","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["hot","new","rating","use"]}}],"responses":{"200":{"description":"模板列表"},"401":{"description":"未认证"}}}},"/templates/{id}":{"get":{"summary":"获取单个模板","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"模板详情"},"401":{"description":"未认证"},"404":{"description":"未找到"}}}},"/workshops/schema":{"get":{"summary":"获取工坊参数 JSON Schema","responses":{"200":{"description":"schema"},"401":{"description":"未认证"}}}},"/health":{"get":{"summary":"健康检查","security":[],"responses":{"200":{"description":"服务状态"}}}}}}