Skip to content

裂变(Variation) ​

根据原图生成相似变体。默认 2.0:相似度滑条 + 可选提示词 + 输出尺寸,一次 1 张。传 engine=v1 则走 1.0。

在编辑器中试用:裂变。

基本信息 ​

项目值
接口路径POST /image/variation
所需 Scopevariation 或 *
任务类型异步,返回 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
}

参数说明 ​

参数类型必填默认值说明
requestIdstring否服务端生成调用方请求 ID,用于幂等去重。省略时服务端生成,并在响应里返回
urlstring是—原图的公开 HTTPS URL
enginestring否v2v2(默认 2.0)或 v1(1.0)
similarityStrengthstring否0.25(2.0)/ 弱(1.0)2.0 为 0~1 滑条,越高越接近原图,也兼容 弱 / 中 / 强。1.0 为 弱 / 中 / 强
promptstring否空2.0 最多 100 字,空则只用相似度种子,超长服务端截断不拒绝。1.0 为可选正向提示词
arstring否original_pixels输出宽高比。engine=v1 时忽略
outputResolutionstring否1k1k / 1.5k / 2k。engine=v1 时忽略
seedinteger否服务端随机仅 2.0。engine=v1 时忽略
countinteger否12.0 服务端锁 1 张。1.0 为 1–4
artEnhanceboolean否false仅 engine=v1
styleIdsinteger[]否[]仅 engine=v1
styleStrengthsnumber[]否与 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"。

妙图设计 API Beta