主题
智能修图(Smart Edit)
根据自然语言提示词对图片进行 AI 编辑,支持替换背景、修改元素、调整氛围等多种操作。
在编辑器中试用:智能修图。
基本信息
| 项目 | 值 |
|---|---|
| 接口路径 | POST /image/smart-edit |
| 所需 Scope | smart_edit 或 * |
| 任务类型 | 异步,返回 taskId |
请求参数
json
{
"requestId": "可选,调用方自定义唯一 ID",
"url": "单张图片 URL(与 urls 二选一)",
"urls": ["多张参考图 URL(与 url 二选一)"],
"prompt": "编辑提示词(必填)",
"promptEnhanced": "可选。传入时出图使用这段文案",
"ar": "不传则按原图宽高比,也可传 1:1",
"count": 1,
"imageModel": "miaotu_v1",
"outputResolution": "1k"
}参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
requestId | string | 否 | 服务端生成 | 调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回 |
url | string | 否 | — | 单张图片 URL,与 urls 二选一。同时提供时使用 urls |
urls | string[] | 否 | — | 多张参考图 URL 列表,与 url 二选一 |
prompt | string | 是 | — | 描述期望修图效果的自然语言提示词。任务记录保存这段原文 |
promptEnhanced | string | 否 | — | 可选增强文案。与 prompt 不同、且不像模型拒答说明时,出图使用这段文案。公测接口不会自动改写提示词 |
ar | string | 否 | 原图比例 | 不传、空字符串或 original 时按输入图宽高比,缩放到所选分辨率档。original_pixels 尽量保持原图像素(边长对齐到 32 的倍数),不按分辨率档放大。也可传 1:1、16:9 等 宽:高;无法解析时按 1:1 |
count | integer | 否 | 1 | 生成张数(1 ~ 4)。miaotu_v1 实际固定为 1,传入 2–4 时收成 1 |
imageModel | string | 否 | miaotu_v1 | 见下方模型表 |
outputResolution | string | 否 | 随模型 | 1k、1.5k、2k。miaotu_v1 默认 1k,三者都可用。其他模型默认 1.5k,传入 2k 时按 1.5k 出图 |
url与urls至少提供其一。本地图片先POST /images/upload,把返回的data.url填进url或urls。分辨率和张数不改变本次计费,仍为 1 个API_CALL。查询任务不会返回promptEnhanced。
模型与输入张数
imageModel | 输入张数上限 | 出图张数 | 分辨率 |
|---|---|---|---|
miaotu_v1(默认) | 5 | 固定 1 | 1k / 1.5k / 2k,默认 1k |
text_enhance_v2、text_enhance_v2_1 | 3 | 1 ~ 4 | 1k / 1.5k,默认 1.5k |
base_v1、base_v2、text_enhance_v1 | 1 | 1 ~ 4 | 1k / 1.5k,默认 1.5k |
portrait_enhance_v1、nano_banana、seedream4(已弃用) | 3 | 1 ~ 4 | 1k / 1.5k,默认 1.5k |
超出输入张数上限时,响应体 code 为 400。旧模型传入 2k 时请求仍然成功,出图按 1.5k。
请求示例
替换背景:
bash
curl -s -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/photo.jpg",
"prompt": "将背景替换为海边日落"
}' \
"https://magiqsight.com/openapi/v1/image/smart-edit"指定模型、张数和分辨率:
bash
curl -s -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/photo.jpg",
"prompt": "增加梦幻光晕效果",
"imageModel": "text_enhance_v1",
"count": 2,
"outputResolution": "1.5k"
}' \
"https://magiqsight.com/openapi/v1/image/smart-edit"响应示例
json
{
"code": 0,
"data": {
"requestId": "req_abc123",
"taskId": "task_xyz"
},
"msg": ""
}获得 taskId 后,通过 GET /tasks/{taskId} 轮询结果。
任务成功(status: 1)后,resultType 为 image,结果在 imageUrls。任务失败(status: 2)时,原因在 resultMetadata。
