LongCat-Image-Edit REST API完全参考:2个curl示例快速调用图像编辑服务

原创2026-10-29 15:10:351,621 阅读
文章标签:人工智能深度学习大模型后端

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 对应,快速定位某次失败请求。

相关源码与配置路径速查

📌 本文所有示例基于项目 README 与源码整理,参数默认值与 api/main.py 中的定义保持一致。

登录后查看全文
LongCat-Image-Edit