当前位置：首页 > news >正文

MusePublic开发者接口文档：REST API设计与错误码详解

news 2026/3/26 18:42:06

MusePublic开发者接口文档：REST API设计与错误码详解

1. 接口概览与设计哲学

1.1 为什么需要一套独立的REST API

你可能已经熟悉MusePublic的Streamlit WebUI——点点鼠标、填填提示词、点下按钮，一张充满电影感的人像就生成了。但当你想把这种艺术创作能力嵌入自己的产品中时，图形界面就不再够用了。

比如，你想为摄影工作室开发一个自动修图+风格化海报生成系统；或者为时尚电商搭建商品图批量重绘流水线；又或者在教育平台里集成AI人像生成作为美术课互动模块……这些场景都需要程序化调用，而不是人工点击。

MusePublic REST API正是为此而生：它不替代WebUI，而是为开发者提供一条干净、稳定、可预测的“技术管道”，把模型的创造力变成你应用里可编排、可监控、可扩展的功能模块。

1.2 设计原则：轻、稳、明

我们没有堆砌复杂协议或强依赖框架，API设计严格遵循三个关键词：

轻（Lightweight）：仅需标准HTTP请求，无需SDK、无需认证密钥（默认本地部署场景），curl、requests、fetch三者皆可开箱即用；
稳（Stable）：所有端点均基于同步推理封装，响应结构统一，无WebSocket长连接、无流式chunk分片，避免前端处理逻辑碎片化；
明（Explicit）：每个字段命名直白（如prompt不叫input_text，negative_prompt不缩写为n_prompt），错误码带语义（422_INVALID_PROMPT_LENGTH比422本身更有信息量），文档即代码契约。

注意：本API面向本地私有部署环境设计，默认信任内网调用。如需公网暴露，请自行前置反向代理并添加身份验证层（如Basic Auth或JWT），本文档不覆盖安全加固方案。

2. 基础接口说明

2.1 根路径健康检查

GET /health

用于快速确认服务进程是否存活、模型是否加载完成。返回纯文本ok，HTTP状态码200。无请求体，无参数。

推荐用法：Kubernetes liveness probe、CI/CD部署后自检脚本
不适用：判断生成能力（不校验GPU显存或调度器状态）

2.2 图像生成主接口

POST /generate

这是唯一的核心生产接口。它接收JSON格式请求体，返回Base64编码的PNG图像数据及元信息。

请求体结构（application/json）

字段名	类型	必填
`prompt`	string	正面提示词，支持中英混合，长度建议30–200字符；过短易导致构图空洞，过长可能触发截断
`negative_prompt`	string	负面提示词，留空则使用内置默认过滤集（含NSFW、低质、畸变等关键词）
`steps`	integer	推理步数，默认30；有效范围20–50，超出将被强制截断为边界值
`seed`	integer	随机种子，默认-1（随机）；若为≥0整数，则保证相同输入下输出完全一致
`width`	integer	图像宽度，默认1024；支持512/768/1024/1280，非列表值将被四舍五入至最近支持值
`height`	integer	图像高度，默认1024；规则同`width`

成功响应（200 OK）

{ "image": "iVBORw0KGgoAAAANSUhEUgAA...", "metadata": { "prompt": "elegant woman in golden hour light, soft focus, cinematic portrait", "negative_prompt": "deformed, blurry, bad anatomy", "steps": 30, "seed": 42, "width": 1024, "height": 1024, "elapsed_ms": 4823 } }

image：PNG图像的Base64字符串（不含data:image/png;base64,前缀），前端可直接用<img src="data:image/png;base64,xxx">渲染
elapsed_ms：从接收到请求到返回响应的总耗时（毫秒），含预处理、推理、编码全过程，可用于性能基线对比

错误响应示例（400 Bad Request）

{ "error": "400_INVALID_JSON", "message": "Request body is not valid JSON" }

3. 错误码体系详解

我们放弃用模糊的HTTP状态码传递业务语义（如全用400），而是采用语义化错误码 + 精确message组合，让调试更高效。所有错误响应均为统一JSON结构：

{ "error": "ERROR_CODE", "message": "Human-readable explanation with actionable hint" }

3.1 客户端错误（4xx）

错误码	HTTP状态码	触发条件	典型修复建议
`400_INVALID_JSON`	400	请求体无法解析为合法JSON	检查是否漏掉逗号、引号未闭合、中文引号混用
`400_MISSING_REQUIRED_FIELD`	400	缺少必填字段（如`prompt`）	查看文档确认必填项，确保字段名拼写准确（区分大小写）
`422_INVALID_PROMPT_LENGTH`	422	`prompt`长度＜10或＞300字符	精简描述或拆分为核心特征（例：把“一个穿红裙子站在巴黎铁塔前微笑的亚洲女孩”简化为“Asian woman in red dress, Eiffel Tower background, smiling, cinematic lighting”）
`422_INVALID_STEPS`	422	`steps`不在20–50范围内	直接设为30，或按需微调±5，避免盲目拉高步数
`422_INVALID_DIMENSIONS`	422	`width`/`height`非512/768/1024/1280之一	使用支持尺寸，或接受自动四舍五入（如传1100→1024）
`422_INVALID_SEED`	422	`seed`为非整数或超出int32范围	传整数，-1表示随机，其他值建议控制在0–2^32-1内

3.2 服务端错误（5xx）

错误码	HTTP状态码	触发条件	排查方向
`500_MODEL_LOAD_FAILED`	500	模型文件损坏、路径错误或safetensors解析失败	检查`models/`目录下`.safetensors`文件完整性，确认权限可读
`500_CUDA_OOM`	500	GPU显存不足导致推理中断（常见于24G以下显卡运行高分辨率）	降低`width`/`height`至768，或启用CPU卸载（见配置说明）
`500_SCHEDULER_ERROR`	500	调度器内部异常（极罕见）	重启服务，检查PyTorch/CUDA版本兼容性（推荐2.1.0+cu121）
`500_IMAGE_ENCODE_FAILED`	500	PNG编码阶段失败（如内存溢出）	减小输出尺寸，或检查磁盘/tmp空间是否充足

小技巧：所有5xx错误均会记录完整traceback到logs/api_error.log，包含时间戳、请求ID、异常类型与堆栈，便于定位深层问题。

4. 实际调用示例

4.1 用curl快速验证

curl -X POST http://localhost:7860/generate \ -H "Content-Type: application/json" \ -d '{ "prompt": "portrait of a jazz singer in 1950s nightclub, neon sign glow, shallow depth of field", "steps": 30, "seed": 12345, "width": 1024, "height": 1024 }' > response.json

执行后，response.json将包含Base64图像。用Python快速解码预览：

import json, base64, io from PIL import Image with open("response.json") as f: data = json.load(f) img_data = base64.b64decode(data["image"]) img = Image.open(io.BytesIO(img_data)) img.show() # 弹出预览窗口

4.2 Python requests完整流程（含错误处理）

import requests import time def musepublic_generate(prompt, negative_prompt="", steps=30, seed=-1): url = "http://localhost:7860/generate" payload = { "prompt": prompt, "negative_prompt": negative_prompt, "steps": steps, "seed": seed } try: start_time = time.time() resp = requests.post(url, json=payload, timeout=300) # 5分钟超时 elapsed = int((time.time() - start_time) * 1000) if resp.status_code == 200: result = resp.json() print(f" 成功生成，耗时 {result['metadata']['elapsed_ms']}ms") return result["image"] else: error = resp.json() print(f" API错误 [{resp.status_code}] {error['error']}: {error['message']}") return None except requests.exceptions.Timeout: print("⏰ 请求超时，请检查服务是否卡顿或GPU负载过高") return None except requests.exceptions.ConnectionError: print("🔌 连接失败，请确认服务地址和端口（默认7860）") return None # 调用示例 image_b64 = musepublic_generate( prompt="fashion editorial shot, model in silk gown, studio lighting, Vogue style", steps=30, seed=888 )

5. 配置与进阶控制

5.1 启动时指定API端口与行为

默认API与WebUI共用同一Flask/FastAPI服务（端口7860），但可通过启动参数分离：

# 启动仅API服务（无WebUI，节省内存） python app.py --api-only --port 8000 # 启动API+WebUI双模式（默认） python app.py --port 7860 # 启用CPU卸载（显存紧张时强制启用） python app.py --cpu-offload

5.2 自定义安全过滤词表

内置过滤已覆盖主流风险场景，但如需强化特定领域管控（如医疗、金融类合规要求），可编辑config/safety_filter.yaml：

# config/safety_filter.yaml default_negative_prompt: > nsfw, nude, naked, deformed, mutated, disfigured, bad anatomy, extra limbs, fused fingers, too many fingers, long neck, ugly, tiling, poorly drawn hands, signature custom_additions: - "medical equipment" # 禁止生成医疗器械特写 - "bank logo" # 禁止生成银行标识

修改后重启服务即可生效，无需重新打包模型。