{"openapi":"3.1.0","info":{"title":"MomoVector SVG API","version":"1.0.0","description":"文字和图片生成 SVG。使用网页账户的额度，文字每次 2 额度，图片每次 1 额度；失败自动返还。异步提交后查询任务状态，所有用户数据端点均需 Bearer Key。每账户每个 UTC 自然分钟 60 次请求，最多 4 个并行生成。"},"servers":[{"url":"/api/v1"}],"security":[{"BearerAuth":[]}],"paths":{"/generations":{"post":{"operationId":"createGeneration","summary":"提交生成任务","description":"返回 202，使用 job.id 查询状态。同一账户以相同 Idempotency-Key 重试相同内容会返回原任务且不重复扣费；内容不同或原作品已删除则返回 409。重试须保留原请求标识。","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,80}$"},"description":"客户端为每个新任务生成 UUID；重试使用同一个值。"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationInput"},"examples":{"text":{"value":{"mode":"text","prompt":"一只可爱的小橘猫","style":"playful"}},"image":{"value":{"mode":"image","image":"data:image/png;base64,...","style":"flat"}}}}}},"responses":{"202":{"description":"任务与用户可见状态。生成中的 url 为 null。","content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/Generation"}}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"任务查询相对地址"},"Retry-After":{"schema":{"type":"integer"},"description":"建议等待的秒数"}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listGenerations","summary":"查看当前账户历史","description":"返回网页和 API 的作品，共享账户所有权。每页 24 条，按创建时间倒序。","parameters":[{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"历史分页结果","content":{"application/json":{"schema":{"type":"object","required":["items","hasMore","nextOffset"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Generation"}},"hasMore":{"type":"boolean"},"nextOffset":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/generations/{id}":{"get":{"operationId":"getGeneration","summary":"查询生成状态","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"任务与用户可见状态。生成中的 url 为 null。","content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/Generation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/generations/{id}/input":{"get":{"operationId":"getLogoSketch","summary":"读取手绘 Logo 的原始草图","description":"仅供作品所属账户访问。仍需 Bearer 鉴权，删除任务后不可读取。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"原始草图图片","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/generations/{id}/references/{index}":{"get":{"operationId":"getStyleReference","summary":"读取已上传的风格参考图","description":"同账户 Bearer 鉴权。仅上传图片可读取，外部链接直接使用 styleReferences[].url；删除作品后不可读取。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"index","in":"path","required":true,"schema":{"type":"integer","minimum":0,"maximum":1}}],"responses":{"200":{"description":"原始参考图片","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/generations/{id}/file":{"get":{"operationId":"downloadGeneration","summary":"下载 SVG","description":"只在任务 completed 时可下载。每次下载也必须携带 Bearer Key，url 不是公开分享链接。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"SVG 文件","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/credits":{"get":{"operationId":"getCredits","summary":"查询账户额度和调用限制","responses":{"200":{"description":"余额、按次费用和限额","content":{"application/json":{"schema":{"type":"object","required":["balance","costs","demo","limits"],"properties":{"balance":{"type":"integer","minimum":0},"costs":{"type":"object","properties":{"text":{"type":"integer","const":2},"image":{"type":"integer","const":1}}},"demo":{"type":"boolean"},"limits":{"type":"object","properties":{"requestsPerMinute":{"type":"integer","const":60},"activeKeys":{"type":"integer","const":10},"concurrentJobs":{"type":"integer","const":4}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"读取 OpenAPI 描述","security":[],"responses":{"200":{"description":"OpenAPI 3.1 文档","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"在网页 /developers 创建 API Key。密钥只显示一次，请仅保存在服务端环境变量中。"}},"schemas":{"StyleReferenceInput":{"type":"array","maxItems":2,"description":"可选风格参考，文字/图片/Logo 均可。最多 2 张，每个上传文件最多 2 MiB（PNG/JPEG/WebP Data URL）；也接受公开 HTTPS 图片直链。按顺序参与幂等校验。链接由模型服务读取，需保持有效；不接受网页、本地地址或带用户凭据的地址。","items":{"type":"string","oneOf":[{"pattern":"^data:image/(png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$","maxLength":2796230},{"pattern":"^https://","format":"uri","maxLength":4096}]}},"GenerationInput":{"oneOf":[{"type":"object","required":["mode","prompt","style"],"not":{"required":["primaryColor"]},"properties":{"styleReferences":{"$ref":"#/components/schemas/StyleReferenceInput"},"mode":{"type":"string","const":"text"},"purpose":{"type":"string","const":"illustration","default":"illustration"},"prompt":{"type":"string","minLength":3,"maxLength":1200},"style":{"type":"string","enum":["playful","flat","minimal","retro","business","tech","3d"]}}},{"type":"object","required":["mode","image","style"],"allOf":[{"if":{"required":["purpose"],"properties":{"purpose":{"const":"logo"}}},"then":{"properties":{"style":{"const":"minimal"}}},"else":{"not":{"required":["primaryColor"]}}}],"properties":{"styleReferences":{"$ref":"#/components/schemas/StyleReferenceInput"},"mode":{"type":"string","const":"image"},"purpose":{"type":"string","enum":["illustration","logo"],"default":"illustration","description":"logo：手绘草图生成图形标志，要求 style=minimal。"},"primaryColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"仅 logo 可用，默认 #202623。作为生成主色方向。"},"prompt":{"type":"string","maxLength":1200},"image":{"type":"string","description":"PNG / JPEG / WebP 的 Base64 Data URL，解码后最多 8 MiB。"},"style":{"type":"string","enum":["playful","flat","minimal","retro","business","tech","3d"]}}}]},"Generation":{"type":"object","required":["id","mode","prompt","style","status","cost","source","demo","error","createdAt","url"],"properties":{"id":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["text","image"]},"purpose":{"type":"string","enum":["illustration","logo"]},"primaryColor":{"type":["string","null"]},"styleReferences":{"type":"array","maxItems":2,"items":{"type":"object","required":["kind","url"],"properties":{"kind":{"type":"string","enum":["upload","url"]},"url":{"type":"string","description":"upload：私有同账户参考图地址；url：用户提供的外部 HTTPS 图片直链。"}}}},"inputUrl":{"type":["string","null"],"description":"Logo 原始草图的私有地址；仍需同账户鉴权。其他作品为 null。"},"prompt":{"type":"string"},"style":{"type":"string","enum":["playful","flat","minimal","retro","business","tech","3d"]},"status":{"type":"string","enum":["queued","running","completed","failed"]},"cost":{"type":"integer"},"source":{"type":"string","enum":["web","api"]},"demo":{"type":"boolean"},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"url":{"type":["string","null"],"description":"完成后为 /api/v1/generations/{id}/file；仍需 Bearer 鉴权。"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}}},"responses":{"Error":{"description":"错误响应。401 表示密钥无效；402 表示余额不足；409 表示幂等冲突或结果未就绪；429 表示调用限频或并行任务超限。","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"当前限流窗口结束的 Unix 秒时间戳"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}