MaaS-MJ

一、请求协议

https

参数名	类型	描述
anthorization	string	鉴权

二、用量

2.1 计费标准

所有接口采用两阶段计费：

阶段	时机	说明
第一阶段	任务创建时	写入 MongoDB，`cost=0`、`success=false` 占位
第二阶段	任务完成时	由轮询（`GET /tob/job/{jobId}`）或悠船回调触发，更新 `cost` 为实际费用并上报计费

计费以悠船返回的 cost.fastCost 为准（快速模式消耗的点数），--draft 模式为标准模式的 0.5 倍费用。

2.2 计费项

触发条件	计费项（chargeItemCode）	用量类型（type）
所有图片接口成功	`unit`	`CREDIT`

三、接口文档

所有接口均需携带鉴权信息，由网关统一处理。

所有 POST 接口均为异步任务，创建成功后返回 jobId，通过查询接口轮询状态。

3.1 文生图

不计费（任务创建阶段），任务完成后按实际消耗计费。

请求 URL

POST /v1/ai/{endpointPath}/tob/diffusion

请求参数

字段	类型	必填	说明
text	string	是	提示词。支持纯文本、嵌入图片 URL（图生图）、及 MJ 参数（如 `--ar 16:9`、`--draft`、`--sref [URL]`、`--oref [URL]` 等）

响应参数

字段	类型	说明
id	string	任务 ID，用于后续轮询
status	integer	任务状态：1=进行中，2=成功，3=失败
comment	string	状态描述
text	string	原始提示词
urls	array\\	生成的图片 URL 列表（4 张），任务进行中时为空数组
seed	integer	本次生成使用的随机种子
cost	object	费用信息（任务完成后填充）
cost.fastCost	number	快速模式消耗点数
cost.feeCost	number	法币费用
cost.relaxCost	number	慢速模式消耗点数

请求示例

{
    "text": "一只戴着帽子的熊猫，水彩风格 --ar 1:1"
}

{
    "text": "帮我生成一张戴着帽子的猎人 --draft"
}

响应示例

{
    "id": "6a13efcec6b99f3fdfec4914",
    "status": 2,
    "comment": "成功",
    "text": "一只戴着帽子的熊猫，水彩风格 --ar 1:1",
    "urls": [
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxx_0.png",
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxx_1.png",
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxx_2.png",
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxx_3.png"
    ],
    "seed": 2464799781,
    "cost": {
        "fastCost": 1.0,
        "feeCost": 60.0,
        "relaxCost": 0.0
    }
}

说明：urls 返回 4 张图，对应 imageNo 0-3，后续二次编辑时用 imageNo 指定操作哪一张。

3.2 查询任务状态

不计费。同时触发第二阶段计费（若任务刚完成）。

请求 URL

GET /v1/ai/{endpointPath}/tob/job/{jobId}

路径参数

字段	类型	必填	说明
jobId	string	是	任务 ID

响应参数

同 3.1 响应参数。

任务状态说明

status 值	含义
1	进行中
2	成功
3	失败

3.3 区域重绘（Inpaint）

请求 URL

POST /v1/ai/{endpointPath}/tob/inpaint

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
mask	object	是	蒙版定义，支持 `areas`（坐标区域）或 `url`（蒙版图片地址）
mask.areas	array	否	多边形区域列表
mask.areas[].width	integer	是	图像宽度，范围 500-4096
mask.areas[].height	integer	是	图像高度，范围 500-4096
mask.areas[].points	array\\	是	多边形顶点坐标，格式 `[x1,y1,x2,y2,...]`，按顺时针方向
mask.url	string	否	蒙版图片地址（黑白图，白色为重绘区）
remixPrompt	string	否	重绘区域的描述提示词

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0,
    "mask": {
        "areas": [{
            "width": 1024,
            "height": 1024,
            "points": [200, 200, 200, 800, 800, 800, 800, 200]
        }]
    },
    "remixPrompt": "Add a red hat"
}

3.4 高清放大（Upscale）

请求 URL

POST /v1/ai/{endpointPath}/tob/upscale

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
type	integer	是	放大模式：0=标准，1=创意，2=v5_2x，3=v5_4x

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0,
    "type": 0
}

3.5 变化（Variation）

请求 URL

POST /v1/ai/{endpointPath}/tob/variation

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
type	integer	是	变化程度：0=轻微变化，1=强烈变化
remixPrompt	string	否	重塑提示词，用于在变化基础上调整方向

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 1,
    "type": 0,
    "remixPrompt": "Make the hat blue"
}

3.6 重新执行任务（Reroll）

用相同参数重新生成一批新图，相当于重新抽卡。

注意：该接口不支持单独传入 callback，回调地址继承自原任务。

请求 URL

POST /v1/ai/{endpointPath}/tob/reroll

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914"
}

3.7 延展（Pan）

向指定方向延伸扩展画面内容。

请求 URL

POST /v1/ai/{endpointPath}/tob/pan

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
direction	integer	是	延展方向：0=下，1=右，2=上，3=左
scale	float	是	延展比例，取值范围 1.1-3.0
remixPrompt	string	否	延展区域提示词

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0,
    "direction": 1,
    "scale": 1.5
}

3.8 扩图（Outpaint）

向四周等比例扩展画面。

请求 URL

POST /v1/ai/{endpointPath}/tob/outpaint

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
scale	float	是	扩展比例，取值范围 1.1-2.0
remixPrompt	string	否	扩图区域提示词

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0,
    "scale": 1.5
}

3.9 重塑（Remix）

在保留原图构图的基础上，用新提示词改变图片内容。

请求 URL

POST /v1/ai/{endpointPath}/tob/remix

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
remixPrompt	string	是	新的提示词
mode	integer	否	重塑模式：0=强烈（默认），1=细微

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0,
    "remixPrompt": "Change the panda to a tiger",
    "mode": 0
}

3.10 编辑（Edit）

在画布上指定区域进行局部编辑。

请求 URL

POST /v1/ai/{endpointPath}/tob/edit

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID
imageNo	integer	是	原始图像编号，取值 0-3
canvas	object	是	画布尺寸
canvas.width	integer	是	画布宽度（像素）
canvas.height	integer	是	画布高度（像素）
imgPos	object	是	图像在画布中的位置
imgPos.width	integer	是	图像宽度（像素）
imgPos.height	integer	是	图像高度（像素）
imgPos.x	integer	是	水平位移（像素）
imgPos.y	integer	是	垂直位移（像素）
remixPrompt	string	是	编辑描述提示词
mask	object	否	原图重绘区域（格式同 3.3 mask）

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0,
    "canvas": {
        "width": 1024,
        "height": 1024
    },
    "imgPos": {
        "width": 512,
        "height": 512,
        "x": 256,
        "y": 256
    },
    "remixPrompt": "Add a forest background"
}

3.11 高级编辑（Upload-Paint）

上传任意图片 URL，通过蒙版指定区域进行局部重绘。不依赖原任务。

请求 URL

POST /v1/ai/{endpointPath}/tob/upload-paint

请求参数

字段	类型	必填	说明
imgUrl	string	是	待编辑图像的 URL 地址
mask	object	是	蒙版定义（格式同 3.3 mask，`areas[].width/height` 须 ≥500）
canvas	object	是	画布尺寸（格式同 3.10 canvas）
imgPos	object	是	图像在画布中的位置（格式同 3.10 imgPos）
remixPrompt	string	是	编辑描述提示词

请求示例

{
    "imgUrl": "https://example.com/image.png",
    "mask": {
        "areas": [{
            "width": 1024,
            "height": 1024,
            "points": [0, 0, 0, 512, 512, 512, 512, 0]
        }]
    },
    "canvas": {
        "width": 1024,
        "height": 1024
    },
    "imgPos": {
        "width": 512,
        "height": 512,
        "x": 256,
        "y": 256
    },
    "remixPrompt": "A beautiful mountain scene with trees"
}

注意：mask.areas[].width 和 height 取值须 ≥ 500，否则悠云返回 400。

3.12 转绘（Retexture）

上传任意图片 URL，用新提示词改变图片的整体风格/纹理。不依赖原任务。

请求 URL

POST /v1/ai/{endpointPath}/tob/retexture

请求参数

字段	类型	必填	说明
imgUrl	string	是	待转绘图像的 URL 地址
remixPrompt	string	是	描述目标风格的提示词

注意：转绘功能需要 v6.1 及以上版本模型。

请求示例

{
    "imgUrl": "https://example.com/image.png",
    "remixPrompt": "Convert to oil painting style"
}

3.13 移除背景（Remove-Background）

自动抠图去除背景，返回透明 PNG。不依赖原任务。

请求 URL

POST /v1/ai/{endpointPath}/tob/remove-background

请求参数

字段	类型	必填	说明
imgUrl	string	是	待处理图像的 URL 地址

请求示例

{
    "imgUrl": "https://example.com/image.png"
}

3.14 增强（Enhance）

对 draft 模式生成的图进行画质增强，提升至正式品质。仅支持通过 --draft 参数创建的任务。

请求 URL

POST /v1/ai/{endpointPath}/tob/enhance

请求参数

字段	类型	必填	说明
jobId	string	是	原始任务 ID（必须为 draft 模式任务）
imageNo	integer	是	原始图像编号，取值 0-3

请求示例

{
    "jobId": "6a13efcec6b99f3fdfec4914",
    "imageNo": 0
}

四、接口分类总览

4.1 直接生成（不依赖原任务）

接口	路径	说明
文生图	`POST /tob/diffusion`	文本/图片生成图像
高级编辑	`POST /tob/upload-paint`	上传图片 + 蒙版局部重绘
转绘	`POST /tob/retexture`	上传图片 + 改变风格
移除背景	`POST /tob/remove-background`	上传图片 + 自动抠图

4.2 二次编辑（基于原任务 jobId）

接口	路径	额外必填参数	说明
区域重绘	`POST /tob/inpaint`	imageNo, mask	指定区域重绘
高清放大	`POST /tob/upscale`	imageNo, type	提升分辨率
变化	`POST /tob/variation`	imageNo, type	保留构图生成变体
重新执行	`POST /tob/reroll`	—	重新生成一批
延展	`POST /tob/pan`	imageNo, direction, scale	向指定方向延伸
扩图	`POST /tob/outpaint`	imageNo, scale	四周等比扩展
重塑	`POST /tob/remix`	imageNo, remixPrompt	保留构图换内容
编辑	`POST /tob/edit`	imageNo, canvas, imgPos, remixPrompt	画布上局部编辑
增强	`POST /tob/enhance`	imageNo	仅限 draft 任务

五、草图模式（Draft Mode）工作流

适用于需要快速迭代创意、降低成本的场景：

步骤 1：POST /tob/diffusion
        text: "描述 --draft"
        → 返回 jobId（draft 任务，费用 0.5 倍，速度 10 倍）

步骤 2：GET /tob/job/{jobId}
        → 轮询直到 status=2（成功）
        → 从 urls[0-3] 中选择满意的图（imageNo 0-3）

步骤 3：POST /tob/enhance
        jobId: 上一步的 jobId
        imageNo: 选中的图片编号
        → 返回高质量正式图

限制：

--draft 不可与 --tile、--oref、--q 4 同时使用

六、错误码

HTTP 状态码	reason	说明
400	Invalid_Argument	请求参数无效
400	VALIDATOR	参数校验失败（如 mask.areas[].width < 500）
400	CODEC	proto 字段不兼容
402	Account_Fee_Not_Enough	账户余额不足
403	Msg_Sensitive	提示词含敏感内容
405	Not_Support	当前操作不支持（如 enhance 接口接收到非 draft 任务）
429	Max_Concurrent_Limited	并发请求数达到上限
500	Internal_Server_Error	悠船服务器内部错误

MaaS-MJ

一、请求协议

Header

二、用量

2.1 计费标准

2.2 计费项

三、接口文档

3.1 文生图

3.2 查询任务状态

3.3 区域重绘（Inpaint）

3.4 高清放大（Upscale）

3.5 变化（Variation）

3.6 重新执行任务（Reroll）

3.7 延展（Pan）

3.8 扩图（Outpaint）

3.9 重塑（Remix）

3.10 编辑（Edit）

3.11 高级编辑（Upload-Paint）

3.12 转绘（Retexture）

3.13 移除背景（Remove-Background）

3.14 增强（Enhance）

四、接口分类总览

4.1 直接生成（不依赖原任务）

4.2 二次编辑（基于原任务 jobId）

五、草图模式（Draft Mode）工作流

六、错误码