主题
裂变(Variation)
根据原图生成相似变体。默认 2.0:相似度滑条 + 可选提示词 + 输出尺寸,一次 1 张。传 engine=v1 则走 1.0。
在编辑器中试用:裂变。
基本信息
| 项目 | 值 |
|---|---|
| 接口路径 | POST /image/variation |
| 所需 Scope | variation 或 * |
| 任务类型 | 异步,返回 taskId;成功时 taskType 为 variation,resultType 为 image |
| 算法 | 默认 2.0(engine=v2,miaotu)。传 engine=v1 切回 1.0 |
请求参数
json
{
"requestId": "可选,调用方自定义唯一 ID",
"url": "原图的公开 HTTPS URL(必填)",
"engine": "可选,v2(默认)或 v1",
"similarityStrength": "0.25",
"prompt": "可选,描述想改的方向,例如换成红裙",
"ar": "original_pixels",
"outputResolution": "1k",
"seed": 42
}参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
requestId | string | 否 | 服务端生成 | 调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回 |
url | string | 是 | — | 原图的公开 HTTPS URL |
engine | string | 否 | v2 | v2(默认 2.0)或 v1(1.0) |
similarityStrength | string | 否 | 0.25(2.0)/ 弱(1.0) | 2.0 为 0~1 滑条,越高越接近原图,也兼容 弱 / 中 / 强。1.0 为 弱 / 中 / 强 |
prompt | string | 否 | 空 | 2.0 最多 100 字,空则只用相似度种子,超长服务端截断不拒绝。1.0 为可选正向提示词 |
ar | string | 否 | original_pixels | 输出宽高比。engine=v1 时忽略 |
outputResolution | string | 否 | 1k | 1k / 1.5k / 2k。engine=v1 时忽略 |
seed | integer | 否 | 服务端随机 | 仅 2.0。engine=v1 时忽略 |
count | integer | 否 | 1 | 2.0 服务端锁 1 张。1.0 为 1–4 |
artEnhance | boolean | 否 | false | 仅 engine=v1 |
styleIds | integer[] | 否 | [] | 仅 engine=v1 |
styleStrengths | number[] | 否 | 与 styleIds 等长的 1.0 | 仅 engine=v1,长度须与 styleIds 一致 |
本地图片先 POST /images/upload,把返回的 data.url 作为 url。
请求示例
默认 2.0:
bash
curl -s -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/photo.jpg"
}' \
"https://magiqsight.com/openapi/v1/image/variation"2.0 指定相似度和改动方向:
bash
curl -s -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/photo.jpg",
"similarityStrength": "0.25",
"prompt": "把外套改成红色",
"ar": "original_pixels",
"outputResolution": "1k"
}' \
"https://magiqsight.com/openapi/v1/image/variation"切回 1.0、一次 2 张:
bash
curl -s -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/photo.jpg",
"engine": "v1",
"similarityStrength": "强",
"count": 2
}' \
"https://magiqsight.com/openapi/v1/image/variation"响应示例
json
{
"code": 0,
"data": {
"requestId": "req_abc123",
"taskId": "task_xyz"
},
"msg": ""
}获得 taskId 后,通过 GET /tasks/{taskId} 轮询结果。
任务成功(status: 1)后,resultType 为 image,结果在 imageUrls,预览在 imagePreviewUrls。任务失败(status: 2)时,原因在 resultMetadata。
json
{
"code": 0,
"data": {
"taskId": "task_xyz",
"taskType": "variation",
"status": 1,
"progress": 1.0,
"resultType": "image",
"imageUrls": ["https://s3.magiqsight.com/private/xxx.png"],
"imagePreviewUrls": ["https://s3.magiqsight.com/private/xxx_thumb.jpg"]
}
}默认 2.0,尽量保持原图尺寸。需要更大画布时传
ar与outputResolution。要 1.0 时传"engine": "v1"。
