AI Agent 接口说明（OpenAPI）

这份文档是给 AI Agent（Claude Code / OpenClaw / 自建 Agent）直接阅读的最小可用说明。 所有接口统一返回：

{ "code": 0, "message": "success", "data": {}, "requestId": "req_xxx" }

错误码：判断失败时，应使用「code 存在且不等于 0」——若响应里 code 为 null 或省略，不要当作错误（避免把 code != 0 误判为失败）。

字段命名：data 内不少接口同时兼容 camelCase 与 snake_case，解析时建议回退读取，例如：

• 任务 ID：jobId / job_id / taskId / task_id
• 上传 URL：signedUrl / signed_url
• 结果图 URL：imageUrl / image_url；结果列表优先 data.results（每项常含 url），勿只认 result.images

鉴权

• Header（二选一）：
  • Authorization: Bearer <你的API Key>
  • X-API-Key: <你的API Key>

获取 API Key：登录 mopng.cn → 进入 /agent 页面 → 创建 Agent API Key（格式 ak_...）。Key 仅保存在你自己的私密配置中，不要提交到代码仓库。

接入方式选择

方式	Base URL	适用场景
MoPNG Agent 协商 API（推荐）	https://agent-api.mopng.cn	让服务端 Agent 接管"选工具/选模型/编排执行"，你的 Agent 只需表达意图、审阅计划、取结果
直连工具 API（本页其余章节）	https://mo-api.mopng.cn	你已明确知道要调用的工具与参数，需要自己控制每一步

两种方式共用同一套 API Key。

Base Path

• 直连工具 API：/api/v1/open（mo-api.mopng.cn）
• MoPNG Agent 协商 API：/api/v1/open/agent（agent-api.mopng.cn）

MoPNG Agent 协商 API（推荐）

适合多步图像工作流（文生图、图生图、抠图、换背景、扩图、放大及其组合）。流程：提交 Brief → 服务端出 Plan →（可多轮修订）→ approve → 轮询 exec 取结果。

1. 查询可用模型（可选）

GET https://agent-api.mopng.cn/api/v1/open/agent/models

返回当前支持文生图的模型清单。

2. 创建会话（提交 Brief）

POST https://agent-api.mopng.cn/api/v1/open/agent/session

{
  "version": "1.0",
  "user_intent": "把这张商品图换成纯白背景，保持阴影自然",
  "spec": {
    "goal": "white-background product photo",
    "subject": {
      "type": "image",
      "reference": "https://example.com/product.png",
      "references": ["https://example.com/product.png"]
    },
    "format": "png"
  },
  "budget": {
    "cost_mode": "balanced",
    "max_cost_points": 10,
    "max_time_sec": 120
  }
}

字段要点：

• spec.subject.reference：必须是可公网访问的 HTTPS URL 或字面量 prompt-only（纯文生图）。本地文件请先上传对象存储拿到 URL，不要发本地路径或 base64；参考图最多 14 张（references）
• spec.format：png / jpg / jpeg / webp，默认 png
• budget.cost_mode：economy / balanced / premium；max_cost_points 超限时服务端会先出 Plan 等你确认
• sensitive（可选）：no_face_alter（默认 false）、no_celebrity / no_brand（默认 true）

响应中的 session_id 用于后续所有步骤。

3. 查看计划

GET /api/v1/open/agent/session/{session_id}/plan

返回服务端规划的执行步骤、所选模型、预估成本。不满意可修订。

4. 修订计划（可选，可多轮）

POST /api/v1/open/agent/session/{session_id}/revision

{
  "plan_id": "plan_xxx",
  "round": 2,
  "feedback": [
    { "field": "style", "comment": "背景改为浅灰渐变" }
  ],
  "reason": "客户要求调整背景色调"
}

修订后重新 GET plan 审阅，直到满意。

5. 批准执行

POST /api/v1/open/agent/session/{session_id}/approve

返回 exec_id。

6. 轮询执行结果

GET /api/v1/open/agent/session/{session_id}/exec

• 成功：交付 result_image_url（视觉问答类 Plan 可能返回 result_text 而非图片）
• 同时报告：steps_log（各步骤执行状态）、实际使用模型、实际成本、ai_labeling
• 失败：状态为 partial_failed / failed，读取 error_code 与 user_message，如实向用户报告，不要声称已生成成功

7. 中断与清理（可选）

• POST /session/{session_id}/interrupt：中断执行中的会话
• DELETE /session/{session_id}：删除会话

协商 API 快速示例

BASE=https://agent-api.mopng.cn/api/v1/open/agent
KEY="Authorization: Bearer $MOPNG_API_KEY"

# 1. 创建会话
SID=$(curl -sS -X POST "$BASE/session" -H "$KEY" -H "Content-Type: application/json" \
  -d '{"version":"1.0","user_intent":"抠出主体并导出透明PNG","spec":{"goal":"cutout transparent png","subject":{"type":"image","reference":"https://example.com/photo.jpg"}}}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['session_id'])")

# 2. 审阅计划 → 3. 批准 → 4. 轮询结果
curl -sS "$BASE/session/$SID/plan"  -H "$KEY"
curl -sS -X POST "$BASE/session/$SID/approve" -H "$KEY"
curl -sS "$BASE/session/$SID/exec"  -H "$KEY"

更完整的客户端实现可直接使用开源技能仓库：gitee.com/jkin8010/mopng-api（SKILL.md 含契约与脚本）。

图片上传（本地图片）

当你有本地图片文件（如 ./photo.jpg）时，需先上传获取可访问 URL，再调用各工具接口。

POST /api/v1/images/upload

• Content-Type: multipart/form-data
• Body: file 字段（图片文件）
• 鉴权: 同 OpenAPI，Authorization: Bearer <你的API Key>

响应示例：

{
  "code": 0,
  "data": {
    "signedUrl": "https://...",
    "signed_url": "https://...",
    "bucket": "...",
    "path": "...",
    "md5": "..."
  }
}

使用返回的 data.signedUrl 或 data.signed_url 作为各接口的 image_url 或 referenceImage。

图片输入规则

图片来源	处理方式
本地文件（如 ./a.png）	先调用 POST /api/v1/images/upload 上传，用返回的 signedUrl / signed_url
远程 URL（如 https://example.com/photo.jpg）	直接传给接口，无需上传

异步任务与轮询端点

当 POST 返回的 data.status 为 pending 或 processing 时，应用同一 API Key 轮询直到 completed 或 failed。不要依赖「仅在请求里开启 async_mode 才轮询」——服务端可能始终返回异步任务。

能力	POST 路径	轮询 GET 路径（将 {id} 换为响应中的任务 ID）
去背景、高清放大	/api/v1/open/image/remove-bg、/api/v1/open/image/upscale	/api/v1/open/image/tasks/{id}
智能扩图、图片翻译	/api/v1/open/image/outpainting、/api/v1/open/image/translation	/api/v1/open/ai/generations/{id}（勿用 /image/tasks）
文生图、图生图	/api/v1/open/ai/generations	/api/v1/open/ai/generations/{id}

任务 ID：从首次（及轮询）响应的 data 读取，兼容 jobId / job_id / taskId / task_id。

结果图片：优先 data.results（一般为对象数组，每项含 url，可兼容 imageUrl / image_url）；若无 results，再回退 data.result 上的 imageUrl / image_url 等。

去背景 / 放大轮询示例：

curl -sS "https://mo-api.mopng.cn/api/v1/open/image/tasks/matting-xxxxxxxx-20260320120000" \
  -H "Authorization: Bearer $MOPNG_API_KEY"

扩图 / 翻译 / 文生图 / 图生图轮询：将路径换为 /api/v1/open/ai/generations/{id}。

轮询建议：间隔 2–5 秒；每次响应同样用「code 存在且非 0」判断错误。

模型发现与选型（文生图/图生图）

text-to-image 和 image-to-image 并不只支持单一模型。 Agent 在发起 /api/v1/open/ai/generations 前，应该先查询可用模型：

• GET /api/v1/open/ai/models
• 可选 Query：type=text_to_image、type=image_edit 等（按能力过滤）

建议执行流程（给 Agent）：

1. 调用 /api/v1/open/ai/models 获取当前环境可用模型清单。
2. 从返回结果中筛选支持当前任务的模型（text_to_image 或 image_to_image）。
3. 根据 model 字段值（对应表中「内部 model_id」），到下方“厂商模型与官方文档”定位对应官方文档。
4. 按官方文档要求校验参数格式（分辨率、比例、图片输入字段、异步机制等）。
5. 最后再调用 /api/v1/open/ai/generations。

备注：若“官方文档”和“本系统行为”不一致，以服务端实际返回为准。

厂商模型与官方文档（用于 Agent 自助查询）

以下为整理内容：

Bytedance（火山引擎 Ark）

• doubao-seedream-4-0-250828（text_to_image / image_to_image） 官方文档：Seedream 4.0 图像生成 API
• doubao-seedream-4-5-251128（text_to_image / image_to_image） 官方文档：即梦 4.5 官方文档

Aliyun（DashScope）

• qwen-image / qwen-image-plus / qwen-image-max（text_to_image） 官方文档：Qwen Image API
• qwen-image-edit-plus（image_to_image / image_edit） 官方文档：Qwen Image Edit API
• wanx-v2（text_to_image / image_to_image / image_edit） 官方文档：通义万相 V2 文生图
• wanx-v2.5（text_to_image / image_to_image / image_edit） 官方文档：通义万相 V2.5 文生图/编辑

给 Agent 的执行指令（可直接复制）

图片输入规则：本地文件需先 POST /api/v1/images/upload 上传，用 data.signedUrl 或 data.signed_url；远程 URL 直接传入。

若 POST 返回 data.status 为 pending/processing：必须轮询——抠图/放大用 GET /api/v1/open/image/tasks/{taskId|task_id}；扩图/翻译/文生图/图生图用 GET /api/v1/open/ai/generations/{jobId|task_id}。鉴权与创建任务相同。结果图优先 data.results[].url。

你在调用 /api/v1/open/ai/generations 做文生图或图生图前，请先：
1) GET /api/v1/open/ai/models?type=text_to_image（或 type=image_edit），拿到可用模型；
2) 选择支持目标能力的 model（列表中的 type 字段值）；
3) 到 docs/server-api/BYTEDANCE_ALIYUN_MODEL_API_REFERENCE.md 里找到该模型的官方文档链接，确认参数格式；
4) 再构造 /api/v1/open/ai/generations 请求。

重要：请求体使用 model（不是 model_id），prompt 放在顶层（不要嵌套在 parameters 里）。
文生图：type=text_to_image，顶层 prompt；
图生图：type=image_to_image，顶层 prompt + referenceImage。

重要约束：image_url / referenceImage

remove-bg、upscale、outpainting、translation 等接口要求 image_url 为可公网访问的 URL；图生图要求 referenceImage 同理。

• 本地图片：先调用 POST /api/v1/images/upload 上传，再用返回的 data.signedUrl / data.signed_url
• 远程 URL：若已是可访问的 https://... 地址，直接传入，无需上传

---

remove-bg（智能抠图）

POST /api/v1/open/image/remove-bg

本地图片需先上传（POST /api/v1/images/upload），远程 URL 可直接传入 image_url。

请求体示例：

{
  "image_url": "https://example.com/input.jpg",
  "output_format": "png",
  "return_mask": false,
  "only_mask": false,
  "async_mode": false
}

返回 data 关键字段（兼容 camelCase / snake_case）：

• taskId / task_id
• status: pending|processing|completed|failed
• 完成时结果图：优先 results 数组中第一项的 url；或 result.imageUrl / result.image_url、result.maskUrl / result.mask_url（return_mask=true 时有 mask）

status 为 pending / processing：用 GET /api/v1/open/image/tasks/{taskId|task_id} 轮询（与是否设置 async_mode 无关）。

---

upscale（高清放大）

POST /api/v1/open/image/upscale

本地图片需先上传，远程 URL 可直接传入 image_url。

请求体示例：

{
  "image_url": "https://example.com/input.jpg",
  "scale": 2,
  "tile_size": 0,
  "tile_pad": 10,
  "output_format": "png",
  "async_mode": false
}

• async_mode：可选；即使未传或为 false，若响应 status 仍为 pending / processing，也应轮询 GET /api/v1/open/image/tasks/{taskId|task_id}。

返回 data：taskId/task_id、status、results 或 result 中的图片 URL 字段（camelCase / snake_case 均可能出现）。

---

outpainting（智能扩图）

POST /api/v1/open/image/outpainting

本地图片需先上传，远程 URL 可直接传入 image_url。

请求体示例：

{
  "provider": "aliyun",
  "model_id": "wanx-outpaint",
  "image_url": "https://example.com/input.jpg",
  "direction": "all",
  "expand_ratio": 0.5,
  "angle": 0,
  "output_ratio": null,
  "best_quality": false
}

异步：若 data.status 为 pending / processing，轮询 GET /api/v1/open/ai/generations/{jobId|taskId|task_id}（不要使用 /api/v1/open/image/tasks/...）。完成后优先从 data.results[].url 取图。

---

translation（图片翻译）

POST /api/v1/open/image/translation

本地图片需先上传，远程 URL 可直接传入 image_url。

请求体示例：

{
  "provider": "aliyun",
  "model_id": "qwen-mt-image",
  "image_url": "https://example.com/text-image.jpg",
  "source_language": "auto",
  "target_language": "en",
  "domain_hint": null,
  "sensitive_word_filter": false,
  "term_intervention": null
}

异步：若 data.status 为 pending / processing，轮询 GET /api/v1/open/ai/generations/{jobId|taskId|task_id}。完成后优先 data.results[].url。错误判断：code is not None and code != 0。

---

text-to-image（文生图）

POST /api/v1/open/ai/generations

最小请求体示例（注意：使用 model 而非 model_id，prompt 在顶层）：

{
  "type": "text_to_image",
  "model": "wanx-v2.5",
  "prompt": "一只红嘴蓝鹊站在树枝上，背景是蓝天白云"
}

字段说明：

• type: text_to_image（必填）
• model: 模型名称（必填），如 wanx-v2.5、qwen-image-plus、doubao-seedream-4，通过 GET /api/v1/open/ai/models 获取
• prompt: 提示词（必填），放在顶层，不要嵌套在 parameters 里

任务查询：

• GET /api/v1/open/ai/generations/{jobId|job_id|task_id}（与创建响应中的 ID 字段一致）
• 完成后优先从 data.results 读取输出（如 results[0].url），兼容旧结构中的单对象 result

---

image-to-image（图生图）

POST /api/v1/open/ai/generations

本地图片需先上传，远程 URL 可直接传入 referenceImages。支持多张参考图；为兼容旧模型，也可以同时传入第一张图片的 referenceImage。

最小请求体示例（注意：使用 model 而非 model_id，prompt 与参考图字段在顶层）：

{
  "type": "image_to_image",
  "model": "wanx-v2.5",
  "prompt": "把天空变成日落金色，保持主体不变",
  "referenceImages": [
    "https://example.com/input-a.jpg",
    "https://example.com/input-b.jpg"
  ],
  "referenceImage": "https://example.com/input-a.jpg"
}

字段说明：

• type: image_to_image（必填）
• model: 模型名称（必填），如 wanx-v2.5、qwen-image-edit-plus
• prompt: 编辑提示词（必填），放在顶层
• referenceImages: 参考图片 URL 数组（推荐，支持多张），放在顶层
• referenceImage: 单张参考图片 URL（兼容字段；传多图时建议设置为 referenceImages[0]）

任务查询：

• GET /api/v1/open/ai/generations/{jobId|job_id|task_id}；结果列表为 data.results