{"openapi":"3.1.0","info":{"title":"小描图片路径识别 API","version":"1.0.0","description":"提交 PNG、JPEG 或 WebP 图片，查询处理状态并下载 SVG 路径识别结果。上传、排队、处理和状态查询不扣费；同一任务首次成功下载结果扣 1 次。","contact":{"name":"小描","url":"https://xiaomiao-ai.com/#pricing"}},"externalDocs":{"description":"开发者文档","url":"https://xiaomiao-ai.com/docs"},"servers":[{"url":"https://xiaomiao-ai.com","description":"生产环境"}],"tags":[{"name":"Images","description":"图片路径识别任务"}],"paths":{"/api/health":{"get":{"summary":"服务健康检查","operationId":"getHealth","responses":{"200":{"description":"服务正常"}}}},"/api/images":{"post":{"tags":["Images"],"summary":"提交图片","description":"上传不扣费。支持 PNG、JPEG 和 WebP，最大 10 MB、3200 万像素。","operationId":"createImageJob","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"任务已接收","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/OutOfCredits"},"413":{"description":"文件或像素超限"},"415":{"description":"图片格式无效或不支持"}}}},"/api/images/{image_id}":{"get":{"tags":["Images"],"summary":"查询任务状态","description":"状态查询不扣费。","operationId":"getImageJob","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ImageId"}],"responses":{"200":{"description":"任务状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"任务不存在或不属于当前 API Key"},"410":{"$ref":"#/components/responses/Expired"}}}},"/api/images/{image_id}/file":{"get":{"tags":["Images"],"summary":"读取原始图片","description":"不扣费。原始图片在结果生成后立即删除。","operationId":"getOriginalImage","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ImageId"}],"responses":{"200":{"description":"原始图片二进制内容"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"任务不存在"},"410":{"$ref":"#/components/responses/Expired"}}}},"/api/images/{image_id}/result":{"get":{"tags":["Images"],"summary":"下载 SVG 结果","description":"同一任务首次成功下载扣 1 次额度，重复下载不再扣费。响应头 x-xiaomiao-charged 表示本次是否扣费。","operationId":"downloadImageResult","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ImageId"}],"responses":{"200":{"description":"SVG 结果","headers":{"x-xiaomiao-charged":{"description":"1 表示本次首次扣费，0 表示未重复扣费","schema":{"type":"string","enum":["0","1"]}},"x-xiaomiao-expires-at":{"description":"结果过期时间","schema":{"type":"string","format":"date-time"}}},"content":{"image/svg+xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/OutOfCredits"},"404":{"description":"任务不存在"},"409":{"description":"结果仍在处理中"},"410":{"$ref":"#/components/responses/Expired"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"小描 API Key（img_live_...）","description":"购买后获得的客户 API Key"}},"parameters":{"ImageId":{"name":"image_id","in":"path","required":true,"description":"上传响应返回的图片任务 ID","schema":{"type":"string","pattern":"^img_[A-Za-z0-9]+$"}}},"schemas":{"JobResponse":{"type":"object","required":["ok","image_id","status","expires_at","result_url","result_file_url","billing","credits_left"],"properties":{"ok":{"type":"boolean","const":true},"image_id":{"type":"string"},"status":{"type":"string","const":"received"},"received_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"result_url":{"type":"string","format":"uri"},"result_file_url":{"type":"string","format":"uri"},"file_url":{"type":"string","format":"uri"},"billing":{"type":"string","const":"first_result_download"},"credits_left":{"type":"integer","minimum":0}}},"JobStatus":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"image_id":{"type":"string"},"status":{"type":"string","enum":["processing","completed"]},"received_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"charged_at":{"type":["string","null"],"format":"date-time"},"billing":{"type":"string","enum":["first_result_download","charged"]},"credits_left":{"type":"integer","minimum":0}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"API Key 缺失、无效或已撤销","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OutOfCredits":{"description":"调用额度已用完","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Expired":{"description":"任务已超过 15 分钟保留期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}