LongCat-Image-Edit REST API完全参考:2个curl示例快速调用图像编辑服务
LongCat-Image-Edit REST API完全参考:2个curl示例快速调用图像编辑服务
LongCat-Image-Edit REST API 服务将美团 LongCat-Image-Edit 图像编辑模型封装为标准 HTTP 接口,部署在华为昇腾 NPU 上。本文提供完整的 REST API 参数参考和 2 个可直接复制的 curl 调用示例,帮你快速完成图像编辑服务的部署、调试与集成。
该模型支持全局编辑、局部编辑、文字修改、参考引导编辑四大能力,编辑指令支持中英文,且非编辑区域的布局、纹理、色调、主体身份保持一致。🌟
服务能力与部署方式
项目采用 FastAPI + Uvicorn + diffusers 技术栈,通过 Docker 容器化部署,核心文件见 README.md:
| 能力 | 说明 |
|---|---|
| 全局编辑 | 按自然语言指令整体重绘图像 |
| 局部编辑 | 仅修改指定区域,其余部分保持不变 |
| 文字修改 | 修改图中文字,支持中英文 |
| 参考引导编辑 | 以参考图为条件引导编辑结果 |
一键部署步骤
方式一:推荐的一键脚本(自动检查模型路径与 NPU 设备、构建镜像、启动容器),见 deploy_longcat_image_edit.sh:
./deploy_longcat_image_edit.sh
方式二:使用 Makefile 分步执行:
make build # 构建Docker镜像
make run # 启动服务
make health # 健康检查
make logs # 查看日志
make stop # 停止服务
服务启动后,API 默认在 http://localhost:18009 提供(端口以你的部署配置为准,docker-compose.yml 中映射为 18005:8000)。推理引擎实现位于 api/inference.py,API 主入口位于 api/main.py。
API 端点总览
服务内置 Swagger 文档,浏览器访问 http://localhost:18009/docs 即可交互式调试。
| 方法 | 端点 | 用途 |
|---|---|---|
| GET | /health |
健康检查,返回服务与模型加载状态 |
| GET | /v1/models |
列出可用模型 |
| POST | /v1/images/edits |
图像编辑(JSON 或 Form 表单两种格式) |
健康检查接口
curl http://localhost:18009/health
返回示例(定义见 api/main.py):
{
"status": "ok",
"model_loaded": true,
"device": "npu:0"
}
💡 首次启动时模型加载可能需要数分钟,
model_loaded为false时请稍后重试。
请求参数完整说明
两种格式共用同一组核心参数(JSON 请求体定义见 api/main.py):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
image |
string / file | 必填 | 输入图像(base64 字符串或文件上传) |
prompt |
string | 必填 | 编辑指令,支持中英文 |
negative_prompt |
string | "" |
负面提示词 |
num_inference_steps |
int | 50 |
推理步数,越大质量越高、耗时越长 |
guidance_scale |
float | 4.5 |
指令引导强度 |
seed |
int | null |
随机种子,相同种子结果可复现 |
num_images_per_prompt |
int | 1 |
每个提示生成的图像数量 |
image_format |
string | "PNG" |
输出图像格式(JSON 格式专用) |
默认推理参数也可在 config/config.yaml 中查看与调整。
curl 示例一:JSON 格式调用(OpenAI 兼容)
适合程序化集成:图片先编码为 base64,响应中的结果同样以 base64 返回(OpenAI 兼容格式)。
curl -X POST http://localhost:18009/v1/images/edits \
-H "Content-Type: application/json" \
-d '{
"image": "<base64_encoded_image>",
"prompt": "将猫变成狗",
"num_inference_steps": 50,
"guidance_scale": 4.5,
"seed": 43
}'
响应结构(见 api/main.py):
{
"created": 1719000000,
"data": [
{
"url": "data:image/png;base64,iVBORw0KGgo...",
"revised_prompt": "将猫变成狗"
}
],
"processing_time": 32.15
}
data[0].url:data URL 格式的 base64 图像,客户端可直接解码保存;processing_time:本次推理耗时(秒),便于监控性能。
curl 示例二:Form 表单调用(文件上传)
更适合新手:直接使用 -F 上传本地图片文件,默认返回 PNG 文件流,可重定向保存:
curl -X POST http://localhost:18009/v1/images/edits \
-F "image=@test.png" \
-F "prompt=将猫变成狗" \
-F "num_inference_steps=50" \
-F "guidance_scale=4.5" \
-F "seed=43" \
-o edited.png
Form 格式还有一个专属参数 return_base64(见 api/main.py):
return_base64=false(默认):直接返回 PNG 图像文件流,响应头附带X-Processing-Time表示耗时;return_base64=true:返回 JSON,其中image_base64字段为编码后的图像。
两个关键注意事项 ⚠️
1. 文字编辑必须用引号
涉及文字生成的编辑任务,目标文本必须用引号括起来(单引号或双引号,中英文皆可),否则渲染效果不佳:
{ "prompt": "将图中的文字改为'Hello World'" }
2. 用 seed 复现实验结果
seed 参数基于 CPU generator 设置(见 api/inference.py)。固定 seed 与其余参数不变时,多次调用可获得一致结果,适合批量实验与回归测试。
常见问题排查
| 现象 | 可能原因与处理 |
|---|---|
返回 503: Model not loaded |
模型尚未加载完成(首次加载较慢),稍等后用 curl /health 确认 model_loaded 为 true |
返回 500 |
查看容器日志 make logs,响应 detail 中带有具体错误信息 |
| 端口连接失败 | 确认部署脚本与 docker-compose.yml 中的端口映射是否一致 |
| NPU 设备报错 | 检查 ASCEND_RT_VISIBLE_DEVICES / ASCEND_DEVICE_ID 环境变量(见 README.md 环境变量表) |
服务已内置链路追踪中间件(config/api_middleware.py),每个请求的响应头会返回 trace-id,排查问题时可与日志中的 trace_id 对应,快速定位某次失败请求。
相关源码与配置路径速查
- API 端点与请求模型:api/main.py
- 推理引擎:api/inference.py
- 模型加载器:api/model_loader.py
- 推理与服务配置:config/config.yaml
- 容器编排(NPU 设备挂载、端口映射):docker-compose.yml
- Docker 镜像构建:Dockerfile
- 容器启动脚本:entrypoint.sh
📌 本文所有示例基于项目 README 与源码整理,参数默认值与 api/main.py 中的定义保持一致。