核心内容摘要
小溪伸进今夜，流淌进无垠星河
MusePublic开发者接口文档REST API设计与错误码详解
接口概览与设计哲学
1 为什么需要一套独立的REST API你可能已经熟悉MusePublic的Streamlit WebUI——点点鼠标、填填提示词、点下按钮一张充满电影感的人像就生成了。
但当你想把这种艺术创作能力嵌入自己的产品中时图形界面就不再够用了。
比如你想为摄影工作室开发一个自动修图风格化海报生成系统或者为时尚电商搭建商品图批量重绘流水线又或者在教育平台里集成AI人像生成作为美术课互动模块……这些场景都需要程序化调用而不是人工点击。
MusePublic REST API正是为此而生它不替代WebUI而是为开发者提供一条干净、稳定、可预测的“技术管道”把模型的创造力变成你应用里可编排、可监控、可扩展的功能模块。
2 设计原则轻、稳、明我们没有堆砌复杂协议或强依赖框架API设计严格遵循三个关键词轻Lightweight仅需标准HTTP请求无需SDK、无需认证密钥默认本地部署场景curl、requests、fetch三者皆可开箱即用稳Stable所有端点均基于同步推理封装响应结构统一无WebSocket长连接、无流式chunk分片避免前端处理逻辑碎片化明Explicit每个字段命名直白如prompt不叫input_textnegative_prompt不缩写为n_prompt错误码带语义422_INVALID_PROMPT_LENGTH比422本身更有信息量文档即代码契约。
注意本API面向本地私有部署环境设计默认信任内网调用。
如需公网暴露请自行前置反向代理并添加身份验证层如Basic Auth或JWT本文档不覆盖安全加固方案。
基础接口说明
1 根路径健康检查GET /health用于快速确认服务进程是否存活、模型是否加载完成。
返回纯文本okHTTP状态码200。
无请求体无参数。
推荐用法Kubernetes liveness probe、CI/CD部署后自检脚本不适用判断生成能力不校验GPU显存或调度器状态
2 图像生成主接口POST /generate这是唯一的核心生产接口。
它接收JSON格式请求体返回Base64编码的PNG图像数据及元信息。
请求体结构application/json字段名类型必填说明promptstring正面提示词支持中英混合长度建议30–200字符过短易导致构图空洞过长可能触发截断negative_promptstring负面提示词留空则使用内置默认过滤集含NSFW、低质、畸变等关键词stepsinteger推理步数默认30有效范围20–50超出将被强制截断为边界值seedinteger随机种子默认-1随机若为≥0整数则保证相同输入下输出完全一致widthinteger图像宽度默认1024支持512/768/1024/1280非列表值将被四舍五入至最近支持值heightinteger图像高度默认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 } }imagePNG图像的Base64字符串不含data:image/png;base64,前缀前端可直接用img srcdata:image/png;base64,xxx渲染elapsed_ms从接收到请求到返回响应的总耗时毫秒含预处理、推理、编码全过程可用于性能基线对比错误响应示例400 Bad Request{ error: 400_INVALID_JSON, message: Request body is not valid JSON }
错误码体系详解我们放弃用模糊的HTTP状态码传递业务语义如全用400而是采用语义化错误码 精确message组合让调试更高效。
所有错误响应均为统一JSON结构{ error: ERROR_CODE, message: Human-readable explanation with actionable hint }
1 客户端错误4xx错误码HTTP状态码触发条件典型修复建议400_INVALID_JSON400请求体无法解析为合法JSON检查是否漏掉逗号、引号未闭合、中文引号混用400_MISSING_REQUIRED_FIELD400缺少必填字段如prompt查看文档确认必填项确保字段名拼写准确区分大小写422_INVALID_PROMPT_LENGTH422prompt长度10或300字符精简描述或拆分为核心特征例把“一个穿红裙子站在巴黎铁塔前微笑的亚洲女孩”简化为“Asian woman in red dress, Eiffel Tower background, smiling, cinematic lighting”422_INVALID_STEPS422steps不在20–50范围内直接设为30或按需微调±5避免盲目拉高步数422_INVALID_DIMENSIONS422width/height非512/768/1024/1280之一使用支持尺寸或接受自动四舍五入如传1100→1024422_INVALID_SEED422seed为非整数或超出int32范围传整数-1表示随机其他值建议控制在0–2^
内
2 服务端错误5xx错误码HTTP状态码触发条件排查方向500_MODEL_LOAD_FAILED500模型文件损坏、路径错误或safetensors解析失败检查models/目录下.safetensors文件完整性确认权限可读500_CUDA_OOM500GPU显存不足导致推理中断常见于24G以下显卡运行高分辨率降低width/height至768或启用CPU卸载见配置说明500_SCHEDULER_ERROR500调度器内部异常极罕见重启服务检查PyTorch/CUDA版本兼容性推荐
2.
0cu121500_IMAGE_ENCODE_FAILED500PNG编码阶段失败如内存溢出减小输出尺寸或检查磁盘/tmp空间是否充足小技巧所有5xx错误均会记录完整traceback到logs/api_error.log包含时间戳、请求ID、异常类型与堆栈便于定位深层问题。
实际调用示例
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 base
b64decode(data[image]) img Image.open(io.BytesIO(img_data)) img.show() # 弹出预览窗口
2 Python requests完整流程含错误处理import requests import time def musepublic_generate(prompt, negative_prompt, steps30, seed-
: 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, jsonpayload, timeout
# 5分钟超时 elapsed int((time.time() - start_time) *
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( 连接失败请确认服务地址和端口默认
return None # 调用示例 image_b64 musepublic_generate( promptfashion editorial shot, model in silk gown, studio lighting, Vogue style, steps30, seed888 )
配置与进阶控制
1 启动时指定API端口与行为默认API与WebUI共用同一Flask/FastAPI服务端口7860但可通过启动参数分离# 启动仅API服务无WebUI节省内存 python app.py --api-only --port 8000 # 启动APIWebUI双模式默认 python app.py --port 7860 # 启用CPU卸载显存紧张时强制启用 python app.py --cpu-offload
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 # 禁止生成银行标识修改后重启服务即可生效无需重新打包模型。
3 性能调优建议针对批量调用并发控制单次请求已做显存复用但高并发5 QPS仍可能触发OOM。
建议客户端加限流如Pythontenacity库重试退避批处理替代方案当前API不支持单请求多图生成。
如需批量任务推荐用seed序列化异步队列如Celery管理避免阻塞主线程缓存策略对固定promptseed组合可在应用层加LRU缓存如functools.lru_cache跳过重复推理。
6.
总结MusePublic REST API不是另一个“玩具级”接口而是为真实工程场景打磨的生产力组件。
它不追求炫技的GraphQL或gRPC而是用最朴素的HTTPJSON把艺术人像生成这件事变得像调用一个函数一样确定、可测、可维护。
你不需要理解EulerAncestralDiscreteScheduler的数学原理也能靠steps30获得最佳平衡不必深究safetensors的内存映射机制单文件加载已为你屏蔽所有风险更不用在文档里翻找晦涩的错误定义——每一个422_XXX都在告诉你“哪里错了”和“怎么改”。
下一步你可以把这段代码粘贴进你的项目替换localhost:7860为实际服务地址用Postman保存常用请求模板快速测试不同提示词效果在CI流水线里加入/health探针确保每次部署后API可用甚至基于此构建一个内部“创意中台”让设计师用自然语言驱动图像生产。
艺术不该被工具链困住。
现在轮到你来定义它的边界。