AI Agent 介面說明（OpenAPI）

這份文件是給 AI Agent（Claude Code / OpenClaw / 自建 Agent）直接閱讀的最小可用說明。

所有介面統一返回：

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

錯誤碼：判斷失敗時，應使用「code 存在且不等於 0」——若響應裡 code 為 null 或省略，不要當作錯誤。

欄位命名：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 https://mo-api.mopng.cn/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": "..."
  }
}

圖片輸入規則

圖片來源	處理方式
本地檔案（如 ./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 https://mo-api.mopng.cn/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 欄位值，到下方「廠商模型與官方文件」定位對應官方文件。
4. 按官方文件要求校驗參數格式（解析度、比例、圖片輸入欄位、非同步機制等）。
5. 最後再呼叫 /api/v1/open/ai/generations。

備註：若「官方文件」和「本系統行為」不一致，以服務端實際返回為準。

廠商模型與官方文件

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) 到廠商官方文件確認該模型的參數格式；
4) 再建構 /api/v1/open/ai/generations 請求。

重要：請求體使用 model（不是 model_id），prompt 放在頂層（不要嵌套在 parameters 裡）。
文生圖：type=text_to_image，頂層 prompt；
圖生圖：type=image_to_image，頂層 prompt + referenceImages。

重要約束：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 https://mo-api.mopng.cn/api/v1/open/image/remove-bg

請求體範例：

{
  "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 https://mo-api.mopng.cn/api/v1/open/image/upscale

請求體範例：

{
  "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 欄位。

---

outpainting（智慧擴圖）

POST https://mo-api.mopng.cn/api/v1/open/image/outpainting

請求體範例：

{
  "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 https://mo-api.mopng.cn/api/v1/open/image/translation

請求體範例：

{
  "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 https://mo-api.mopng.cn/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 https://mo-api.mopng.cn/api/v1/open/ai/generations

本地圖片需先上傳，遠端 URL 可直接傳入 referenceImages。支援多張參考圖；為相容舊模型，也可以同時傳入第一張圖片的 referenceImage。

最小請求體範例：

{
  "type": "image_to_image",
  "model": "qwen-image-edit-plus",
  "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