{"openapi":"3.1.0","info":{"title":"Cosmo-Core AI视觉 API","version":"v1","description":"AI视觉同步识别、异步任务、业务反馈与回调契约。认证方式：请求头 X-API-Key。"},"paths":{"/v1/vision/models":{"get":{"summary":"发现可用模型","description":"返回当前应用可用的模型、默认模型、类别和激活权重哈希。","operationId":"vision_models_v1_vision_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}}}}}},"/v1/vision/predict":{"post":{"summary":"图片 URL 同步识别","description":"用授权域名的图片 URL 做同步推理，直接返回识别结果。","operationId":"vision_predict_v1_vision_predict_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/predict_upload":{"post":{"summary":"上传图片同步识别","description":"multipart 上传图片做同步推理，返回与 URL 识别一致的结果。","operationId":"vision_predict_upload_v1_vision_predict_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_vision_predict_upload_v1_vision_predict_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/feedback":{"post":{"summary":"回传业务反馈","description":"按 request_id 或图片来源提交业务正确/错误反馈，进入复核回流。","operationId":"vision_feedback_v1_vision_feedback_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackReq"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/tasks":{"post":{"summary":"创建异步任务（URL）","description":"提交图片 URL 创建异步识别任务，立即返回 task_id。","operationId":"create_task_v1_vision_tasks_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128,"default":"","title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskView"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"列出最近任务","description":"列出当前应用最近的异步任务。","operationId":"list_tasks_v1_vision_tasks_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/tasks/upload":{"post":{"summary":"创建异步任务（上传）","description":"上传图片创建异步识别任务，立即返回 task_id。","operationId":"create_task_upload_v1_vision_tasks_upload_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128,"default":"","title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_task_upload_v1_vision_tasks_upload_post"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskView"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/tasks/{task_id}":{"get":{"summary":"查询任务详情","description":"查询任务状态、结果和最近回调记录。","operationId":"get_task_v1_vision_tasks__task_id__get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/tasks/{task_id}/cancel":{"post":{"summary":"取消任务","description":"取消排队或运行中的异步任务。","operationId":"cancel_task_v1_vision_tasks__task_id__cancel_post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskView"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/vision/tasks/{task_id}/callback/retry":{"post":{"summary":"重试回调","description":"手动重试失败的任务回调。","operationId":"retry_callback_v1_vision_tasks__task_id__callback_retry_post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_create_task_upload_v1_vision_tasks_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"JPEG/PNG/WEBP 图片文件"},"model":{"type":"string","title":"Model","description":"模型名；不传使用应用默认模型","default":""},"conf":{"type":"number","maximum":1.0,"minimum":0.05,"title":"Conf","description":"置信度阈值 0.05–1","default":0.4},"priority":{"type":"integer","maximum":5.0,"minimum":0.0,"title":"Priority","description":"排队优先级 0–5","default":0}},"type":"object","required":["file"],"title":"Body_create_task_upload_v1_vision_tasks_upload_post"},"Body_vision_predict_upload_v1_vision_predict_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"JPEG/PNG/WEBP 图片文件，最大 10 MB、2500 万像素"},"model":{"type":"string","title":"Model","description":"模型名；不传使用应用默认模型","default":""},"conf":{"type":"number","maximum":1.0,"minimum":0.05,"title":"Conf","description":"置信度阈值 0.05–1","default":0.4}},"type":"object","required":["file"],"title":"Body_vision_predict_upload_v1_vision_predict_upload_post"},"CallbackLog":{"properties":{"id":{"type":"string","title":"Id","description":"日志 ID","default":""},"task_id":{"type":"string","title":"Task Id","description":"任务 ID","default":""},"attempt":{"type":"integer","title":"Attempt","description":"第几次尝试","default":0},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"HTTP 状态码"},"response":{"type":"string","title":"Response","description":"响应摘要","default":""},"error":{"type":"string","title":"Error","description":"错误信息","default":""},"ts":{"type":"string","title":"Ts","description":"尝试时间","default":""}},"type":"object","title":"CallbackLog"},"Detection":{"properties":{"class_id":{"type":"integer","title":"Class Id","description":"类别 ID"},"class":{"type":"string","title":"Class","description":"类别名称"},"confidence":{"type":"number","title":"Confidence","description":"置信度 0–1"},"bbox":{"items":{"type":"number"},"type":"array","title":"Bbox","description":"像素坐标 [x1,y1,x2,y2]，左上角原点"}},"type":"object","required":["class_id","class","confidence","bbox"],"title":"Detection"},"FeedbackReq":{"properties":{"request_id":{"type":"string","maxLength":64,"title":"Request Id","description":"识别接口返回的 request_id；与 image 二选一","default":""},"image":{"type":"string","maxLength":4096,"title":"Image","description":"完整图片来源；与 request_id 二选一","default":""},"verdict":{"type":"string","enum":["wrong","correct"],"title":"Verdict","description":"业务判定：wrong 误检，correct 正确"},"expected_class":{"type":"string","maxLength":128,"title":"Expected Class","description":"业务期望类别，wrong 时建议填写","default":""},"note":{"type":"string","maxLength":2000,"title":"Note","description":"业务备注","default":""}},"type":"object","required":["verdict"],"title":"FeedbackReq"},"FeedbackResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"是否受理"},"request_id":{"type":"string","title":"Request Id","description":"实际关联的识别 ID"},"verdict":{"type":"string","title":"Verdict","description":"wrong 或 correct"},"entered_review_pool":{"type":"boolean","title":"Entered Review Pool","description":"是否因此进入待复核池"},"duplicate":{"type":"boolean","title":"Duplicate","description":"是否为重复反馈"},"review_status":{"type":"string","title":"Review Status","description":"当前复核状态"},"already_reviewed":{"type":"boolean","title":"Already Reviewed","description":"是否已有人工复核结论"}},"type":"object","required":["ok","request_id","verdict","entered_review_pool","duplicate","review_status","already_reviewed"],"title":"FeedbackResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ModelInfo":{"properties":{"name":{"type":"string","title":"Name","description":"模型名，调用时传给 model"},"version":{"type":"string","title":"Version","description":"当前激活权重版本"},"description":{"type":"string","title":"Description","description":"模型用途说明","default":""},"classes":{"additionalProperties":{"type":"string"},"type":"object","title":"Classes","description":"class_id 到类别名的映射"},"sha256":{"type":"string","title":"Sha256","description":"激活权重 SHA-256","default":""},"pending_migration":{"type":"boolean","title":"Pending Migration","description":"类别定义与权重不一致时暂不可推理","default":false}},"type":"object","required":["name","version"],"title":"ModelInfo"},"ModelsResponse":{"properties":{"default_model":{"type":"string","title":"Default Model","description":"未指定 model 时使用的默认模型"},"product":{"additionalProperties":true,"type":"object","title":"Product","description":"产品信息：id、name"},"models":{"items":{"$ref":"#/components/schemas/ModelInfo"},"type":"array","title":"Models","description":"当前应用可用模型"}},"type":"object","required":["default_model"],"title":"ModelsResponse"},"OkResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"操作是否成功"}},"type":"object","required":["ok"],"title":"OkResponse"},"Performance":{"properties":{"fetch_ms":{"type":"number","title":"Fetch Ms","description":"图片来源获取耗时（毫秒）","default":0},"normalize_ms":{"type":"number","title":"Normalize Ms","description":"图片规范化耗时（毫秒）","default":0},"ingest_ms":{"type":"number","title":"Ingest Ms","description":"图片入口总耗时（毫秒）","default":0},"inference_ms":{"type":"number","title":"Inference Ms","description":"模型推理耗时（毫秒）","default":0},"draw_ms":{"type":"number","title":"Draw Ms","description":"结果图绘制耗时（毫秒）","default":0},"persist_ms":{"type":"number","title":"Persist Ms","description":"识别结果入库耗时（毫秒）","default":0},"server_total_ms":{"type":"number","title":"Server Total Ms","description":"服务端总耗时（毫秒）","default":0},"image_bytes":{"type":"integer","title":"Image Bytes","description":"规范化后图片字节数","default":0}},"type":"object","title":"Performance"},"PredictReq":{"properties":{"image":{"type":"string","maxLength":4096,"minLength":1,"title":"Image","description":"图片 URL；需加入平台图片域名白名单"},"model":{"type":"string","maxLength":64,"title":"Model","description":"模型名；不传时使用应用默认模型","default":""},"conf":{"type":"number","maximum":1.0,"minimum":0.05,"title":"Conf","description":"置信度阈值，低于该值的检测框不返回","default":0.4},"priority":{"type":"integer","maximum":5.0,"minimum":0.0,"title":"Priority","description":"同步接口保留字段，当前不参与排队","default":0}},"type":"object","required":["image"],"title":"PredictReq"},"PredictResponse":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"识别记录 ID，用于反馈、复核和排障"},"model":{"type":"string","title":"Model","description":"实际使用的模型"},"model_version":{"type":"string","title":"Model Version","description":"实际权重版本"},"model_sha256":{"type":"string","title":"Model Sha256","description":"实际权重哈希"},"source":{"type":"string","title":"Source","description":"服务端原图相对路径；拉取需带 API Key"},"count":{"type":"integer","title":"Count","description":"达到置信度阈值的检测框数量"},"detections":{"items":{"$ref":"#/components/schemas/Detection"},"type":"array","title":"Detections","description":"检测结果"},"annotated_image":{"type":"string","title":"Annotated Image","description":"画框后的图片相对路径"},"image_width":{"type":"integer","title":"Image Width","description":"原图像素宽度"},"image_height":{"type":"integer","title":"Image Height","description":"原图像素高度"},"performance":{"$ref":"#/components/schemas/Performance","description":"各阶段耗时"}},"type":"object","required":["request_id","model","model_version","model_sha256","source","count","annotated_image","image_width","image_height"],"title":"PredictResponse"},"TaskCreate":{"properties":{"image":{"type":"string","maxLength":4096,"minLength":1,"title":"Image","description":"图片 URL；需加入平台图片域名白名单"},"model":{"type":"string","maxLength":64,"title":"Model","description":"模型名；不传时使用应用默认模型","default":""},"conf":{"type":"number","maximum":1.0,"minimum":0.05,"title":"Conf","description":"置信度阈值","default":0.4},"priority":{"type":"integer","maximum":5.0,"minimum":0.0,"title":"Priority","description":"排队优先级 0–5，越大越优先","default":0}},"type":"object","required":["image"],"title":"TaskCreate"},"TaskDetail":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"任务 ID"},"status":{"type":"string","title":"Status","description":"queued/running/succeeded/failed/canceled"},"priority":{"type":"integer","title":"Priority","description":"优先级 0–5","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"失败或取消原因"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"成功时的识别结果"},"callback_status":{"type":"string","title":"Callback Status","description":"none/pending/sent/failed","default":"none"},"callback_attempts":{"type":"integer","title":"Callback Attempts","description":"已尝试回调次数","default":0},"callback_next_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Next At","description":"下一次回调时间"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"应用回调地址"},"created_at":{"type":"string","title":"Created At","description":"创建时间","default":""},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"开始执行时间"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At","description":"完成时间"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"结果过期时间"},"attempts":{"type":"integer","title":"Attempts","description":"执行尝试次数","default":0},"account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id","description":"账号 ID"},"app_id":{"type":"string","title":"App Id","description":"应用 ID","default":""},"actor":{"type":"string","title":"Actor","description":"创建人","default":""},"product_id":{"type":"string","title":"Product Id","description":"产品 ID","default":"vision"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"模型名"},"conf":{"type":"number","title":"Conf","description":"置信度阈值","default":0.4},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"图片 URL"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"幂等键"},"callbacks":{"items":{"$ref":"#/components/schemas/CallbackLog"},"type":"array","title":"Callbacks","description":"最近回调记录"}},"type":"object","required":["task_id","status"],"title":"TaskDetail"},"TaskList":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TaskView"},"type":"array","title":"Items","description":"任务列表"}},"type":"object","title":"TaskList"},"TaskView":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"任务 ID"},"status":{"type":"string","title":"Status","description":"queued/running/succeeded/failed/canceled"},"priority":{"type":"integer","title":"Priority","description":"优先级 0–5","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"失败或取消原因"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"成功时的识别结果"},"callback_status":{"type":"string","title":"Callback Status","description":"none/pending/sent/failed","default":"none"},"callback_attempts":{"type":"integer","title":"Callback Attempts","description":"已尝试回调次数","default":0},"callback_next_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Next At","description":"下一次回调时间"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"应用回调地址"},"created_at":{"type":"string","title":"Created At","description":"创建时间","default":""},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"开始执行时间"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At","description":"完成时间"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"结果过期时间"},"attempts":{"type":"integer","title":"Attempts","description":"执行尝试次数","default":0},"account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id","description":"账号 ID"},"app_id":{"type":"string","title":"App Id","description":"应用 ID","default":""},"actor":{"type":"string","title":"Actor","description":"创建人","default":""},"product_id":{"type":"string","title":"Product Id","description":"产品 ID","default":"vision"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"模型名"},"conf":{"type":"number","title":"Conf","description":"置信度阈值","default":0.4},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"图片 URL"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"幂等键"}},"type":"object","required":["task_id","status"],"title":"TaskView"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"应用密钥，只在创建时展示一次"}}},"servers":[{"url":"http://ai.banmahuanao.com"}],"tags":[{"name":"AI视觉","description":"产品命名空间 /v1/vision"}],"security":[{"ApiKeyAuth":[]}]}