一键换色 V2 API 接口文档

一、换色任务

POST/image/v2/make/changeColorV2application/json

接口说明

对商品图片进行智能换色，支持单图和多图请求，以及两种换色模式（二选一）：

颜色模式（colors）：传入 HEX 颜色列表，每种颜色独立生成一张换色结果图
参考图模式（refImageUrls）：传入参考图 URL 列表，AI 从参考图提取颜色并应用换色

原图支持两种传法（二选一）：单图使用 imageUrl，多图使用 imageUrls。多图结果数量为「原图数量 × 颜色数量/参考图数量」，仍返回一个普通换色任务 ID。

无需抠图，AI 自动识别并替换商品主体颜色。消耗算力 = 原图数 × 颜色数/参考图数 × 单张扣点，单张扣点只由「模型 + 品质」决定，与图片分辨率无关。

参数说明

imageUrlstring条件必填

单张原图URL（兼容单图请求），与 imageUrls 二选一

格式：jpg、jpeg、png、webp尺寸：300×300～4096×4096

imageUrlsarray[string]条件必填

多张原图URL列表，与 imageUrl 二选一
数量范围：1 ~ 12

colorsarray[string]条件必填

目标颜色列表，支持多种格式
数量范围：1 ~ 25
与 refImageUrls 二选一

refImageUrlsarray[string]条件必填

参考图URL列表（参考图换色模式）
数量范围：1 ~ 25
与 colors 二选一

colorSubjectstring必填

换色部位描述，如"上装"、"下装"、"鞋面"等

modelstring可选默认GPT_2_5_IMAGE

模型选择，可选值见下方扣费标准

qualitystring可选默认medium

输出品质，可选值以后台模型配置的支持品质为准，当前为 low / medium / high。未配置品质维度的模型忽略该参数，传入未配置档位时回落默认品质

注意：
- imageUrl 和 imageUrls 必须二选一
- colors 和 refImageUrls 必须二选一，同时传或都不传会返回参数校验错误
- 单图输出图片数量由 colors 或 refImageUrls 数组长度自动确定，无需额外传入 outputNum
- 多图请求的输出数量为原图数量乘以颜色/参考图数量，结果按原图顺序和颜色/参考图顺序展开
- 通过 OpenAPI 传入的外链图片统一按 2K 计费，无需传分辨率参数

模式一：颜色模式（colors）

colors 支持的格式类型

colors 中的每个元素为字符串类型，支持以下三种颜色格式：

格式类型	说明	示例
HEX（推荐）	十六进制颜色码，最精确	`"#FF0000"`、`"#00FF00"`、`"#0000FF"`
HSB	色相-饱和度-亮度表示法	`"hsb(0, 100%, 100%)"`、`"hsb(120, 100%, 50%)"`
RGB	红-绿-蓝函数表示法	`"rgb(255, 0, 0)"`、`"rgb(0, 255, 0)"`

建议：推荐使用 HEX 格式，颜色还原最精确。

各格式参数限制

格式	限制说明
HEX	仅支持 6 位十六进制 `#RRGGBB`，大小写不敏感。不支持 3 位短格式（如 `#FFF`）和 8 位格式（如 `#FF0000FF`）
HSB	H（色相）为 0~360 的整数；S（饱和度）和 B（亮度）为 0~100 的整数，必须带 `%` 后缀。格式严格为 `hsb(H, S%, B%)`，大小写不敏感
RGB	红/绿/蓝每个通道为 0~255 的整数。格式严格为 `rgb(R, G, B)`，大小写不敏感

注意：数值超出范围将返回参数校验错误，不会自动修正。空白值（空字符串或全空格）同样会被拒绝。

格式示例

JSON

// 纯 HEX（推荐）
"colors": ["#FF0000", "#00FF00", "#0000FF"]

// HSB 格式
"colors": ["hsb(0, 100%, 100%)", "hsb(240, 100%, 50%)"]

// RGB 格式
"colors": ["rgb(255, 0, 0)", "rgb(255, 255, 0)"]

// 混用格式
"colors": ["#FF6B6B", "hsb(0, 0%, 50%)", "rgb(255, 255, 0)"]

常见格式错误

错误示例	错误原因
`"#FFF"`	不支持 3 位短 HEX
`"hsb(400, 100%, 100%)"`	H 超出 0~360 范围
`"hsb(0, 120%, 50%)"`	S 超出 0~100 范围
`"rgb(300, 0, 0)"`	R 超出 0~255 范围
`"red"`	不支持颜色名称
`"hsl(0, 100%, 50%)"`	不支持 HSL 格式
`""`	颜色值不能为空

模式二：参考图模式（refImageUrls）

传入参考图 URL，AI 自动从参考图中提取主色调并应用于原图进行换色。

参考图要求

支持 jpg、jpeg、png、webp 格式
每张参考图应含有清晰的主色调
数量范围：1 ~ 25 张

请求示例

颜色模式

JSON

{
  "imageUrl": "https://test-file-ai.linkfox.com/UPLOAD/product.jpg",
  "colors": ["#FFFFFF", "#000000", "#FF6B6B", "#4ECDC4"],
  "colorSubject": "上装",
  "model": "GPT_2_5_IMAGE",
  "quality": "medium"
}

model 与 quality 为选填，不传时按默认模型 GPT_2_5_IMAGE + 中品质 medium 计费与生成。

参考图模式

JSON

{
  "imageUrl": "https://test-file-ai.linkfox.com/UPLOAD/product.jpg",
  "refImageUrls": [
    "https://test-file-ai.linkfox.com/UPLOAD/ref1.jpg",
    "https://test-file-ai.linkfox.com/UPLOAD/ref2.jpg"
  ],
  "colorSubject": "上装"
}

多图颜色模式

JSON

{
  "imageUrls": [
    "https://test-file-ai.linkfox.com/UPLOAD/product-1.jpg",
    "https://test-file-ai.linkfox.com/UPLOAD/product-2.jpg"
  ],
  "colors": ["#FFFFFF", "#000000"],
  "colorSubject": "上装"
}

响应参数

traceIdstring

链路ID

codestring

状态码 200 为成功其他为失败

msgstring

成功/失败描述

msgKeystring

失败描述错误码，状态码不等于200时存在

dataobject

对象字段

idnumber

任务ID

响应示例

JSON

{
  "traceId": "f6e0fe4f360f78445c2c5d52f2414dea",
  "code": "200",
  "msg": "成功",
  "data": {
    "id": 123456
  }
}

查询结果接口说明

提交任务后，使用通用查询结果接口获取换色结果。

查询结果示例

JSON

{
  "msg": "成功",
  "code": 200,
  "traceId": "081d9474c851ad19a0e7dd2380811f1f",
  "data": {
    "id": "2008750323222487040",
    "status": 3,
    "errorCode": "",
    "errorMsg": "",
    "resultList": [
      {
        "id": "7854358",
        "status": 1,
        "errorCode": "",
        "errorMsg": "",
        "url": "https://test-file-ai.linkfox.vip/CHANGE_COLOR_V2/result_1.jpg",
        "width": 2048,
        "height": 2048,
        "format": "jpg",
        "extendField": {}
      },
      {
        "id": "7854359",
        "status": 1,
        "errorCode": "",
        "errorMsg": "",
        "url": "https://test-file-ai.linkfox.vip/CHANGE_COLOR_V2/result_2.jpg",
        "width": 2048,
        "height": 2048,
        "format": "jpg",
        "extendField": {}
      }
    ]
  }
}

任务状态说明

status	说明
1	排队中
2	生成中
3	成功
4	失败

本接口使用通用「获取作图结果」查询，任务 status 与该页一致，不是另一套内部状态码。

注意：单图结果列表顺序与请求中 colors 或 refImageUrls 数组顺序一致。多图结果按原图顺序展开，每张原图内部再按 colors 或 refImageUrls 顺序排列。

错误码

错误描述	说明
imageUrl、imageUrls 必须二选一	两个参数同时传入或都未传入
图片链接不能为空	`imageUrl` 或 `imageUrls` 中的图片URL为空
原图数量不能超过12张	`imageUrls` 数组长度超过12
colors、refImageUrls 必须二选一	两个参数同时传入或都未传入
目标颜色列表不能为空	颜色模式下 `colors` 为空数组
目标颜色数量不能超过25个	`colors` 数组长度超过 25
参考图列表不能为空	参考图模式下 `refImageUrls` 为空数组
参考图数量不能超过25张	`refImageUrls` 数组长度超过 25
不支持的颜色格式	`colors` 中元素不是 HEX / HSB / RGB 格式
颜色值不能为空	`colors` 中存在空字符串或空白值
换色部位不能为空	`colorSubject` 参数未传或为空

二、色卡颜色分析（预处理）

接口说明

从色卡图片中提取颜色信息（颜色名称 + HEX 色号）。该接口为异步接口，提交任务后轮询结果。

适用场景：用户上传色卡图片 → 调用本接口提取颜色列表 → 拿到 HEX 色号后调用换色任务接口的颜色模式。

2.1 提交分析任务

POST/v2/process/result/colorCardAnalyze/createapplication/json

参数说明

imageUrlsarray[string]必填

色卡图片URL列表

格式：jpg、jpeg、png、webp

请求示例

JSON

{
  "imageUrls": [
    "https://test-file-ai.linkfox.com/UPLOAD/color-card-1.jpg",
    "https://test-file-ai.linkfox.com/UPLOAD/color-card-2.jpg"
  ]
}

响应参数

traceIdstring

链路ID

codestring

状态码 200 为成功其他为失败

msgstring

成功/失败描述

dataobject

对象字段

idstring

任务ID，用于轮询结果

typenumber

任务类型（固定为 7）

响应示例

JSON

{
  "traceId": "a1b2c3d4e5f6",
  "code": "200",
  "msg": "成功",
  "data": {
    "id": "1930923414987821056",
    "type": 7
  }
}

2.2 查询分析结果

POST/v2/process/result/colorCardAnalyze/infoapplication/json

参数说明

idstring必填

任务ID（提交任务时返回的 id）

请求示例

JSON

{
  "id": "1930923414987821056"
}

响应参数

traceIdstring

链路ID

codestring

状态码 200 为成功其他为失败

msgstring

成功/失败描述

dataobject

对象字段

statusnumber

任务状态

errorstring

错误信息（status=4时有值）

countnumber

消耗点数

resultobject

分析结果（status=3时有值）

对象字段

resultsarray[object]

逐张色卡分析结果

数组元素

imageUrlstring

色卡图片URL

colorsarray[object]

提取的颜色列表

数组元素

colorNameCnstring

颜色中文名称

hexFinalstring

十六进制色号

响应示例

JSON

{
  "traceId": "x1y2z3",
  "code": "200",
  "msg": "成功",
  "data": {
    "status": 3,
    "count": 0,
    "result": {
      "results": [
        {
          "imageUrl": "https://test-file-ai.linkfox.com/UPLOAD/color-card-1.jpg",
          "colors": [
            { "colorNameCn": "粉红色", "hexFinal": "#EE97A6" },
            { "colorNameCn": "深红色", "hexFinal": "#C43E2C" },
            { "colorNameCn": "米白色", "hexFinal": "#F5F0E8" }
          ]
        },
        {
          "imageUrl": "https://test-file-ai.linkfox.com/UPLOAD/color-card-2.jpg",
          "colors": [
            { "colorNameCn": "天蓝色", "hexFinal": "#5DADE2" },
            { "colorNameCn": "藏青色", "hexFinal": "#2C3E50" }
          ]
        }
      ]
    }
  }
}

2.3 任务状态说明

status	说明
1	已创建（等待处理）
2	处理中
3	成功
4	失败

注意：部分色卡解析失败时，成功的图片仍会返回结果，失败的图片不在 results 中。建议对比请求的 imageUrls 数量与返回的 results 数量判断是否有遗漏。

2.4 错误码

错误描述	说明
图片URL列表不能为空	`imageUrls` 参数未传或为空数组

三、推荐调用流程

流程一：已知目标颜色（直接换色）

模板

POST /image/v2/make/changeColorV2
  body: { imageUrl, colors: ["#FF0000", "#00FF00"], colorSubject: "上装" }
  → 返回 { data: { id: 任务ID } }

轮询查询结果接口 → status=3 时获取 resultList

流程二：从色卡提取颜色再换色

模板

Step 1: 提交色卡分析
POST /v2/process/result/colorCardAnalyze/create
  body: { imageUrls: ["https://.../card.jpg"] }
  → 返回 { data: { id: "1930923414987821056", type: 7 } }

Step 2: 轮询色卡分析结果
POST /v2/process/result/colorCardAnalyze/info
  body: { id: "1930923414987821056" }
  → status=3 时拿到 result.results[].colors: [{ colorNameCn, hexFinal }]

Step 3: 用提取的颜色换色
POST /image/v2/make/changeColorV2
  body: { imageUrl, colors: ["#EE97A6", "#C43E2C"], colorSubject: "上装" }
  → 返回任务ID，轮询获取结果

流程三：参考图换色

模板

POST /image/v2/make/changeColorV2
  body: { imageUrl, refImageUrls: ["https://.../ref1.jpg"], colorSubject: "上装" }
  → 返回 { data: { id: 任务ID } }

轮询查询结果接口 → status=3 时获取 resultList

扣费标准

正在读取当前模型扣点...

消耗算力 = 原图数 × 颜色数或参考图数 × 单张扣点；OpenAPI 外链图片按 2K 计费。多图请求按每张结果图单独计费。

创建上限

配置项	上限
创建中 / 生成中任务上限	100 个

一键换色V2

一、换色任务

接口说明

参数说明

模式一：颜色模式（colors）

colors 支持的格式类型

各格式参数限制

格式示例

常见格式错误

模式二：参考图模式（refImageUrls）

参考图要求

请求示例

颜色模式

参考图模式

多图颜色模式

响应参数

响应示例

查询结果接口说明

任务状态说明

错误码

二、色卡颜色分析（预处理）

接口说明

2.1 提交分析任务

参数说明

请求示例

响应参数

响应示例

2.2 查询分析结果

参数说明

请求示例

响应参数

响应示例

2.3 任务状态说明

2.4 错误码

三、推荐调用流程

流程一：已知目标颜色（直接换色）

流程二：从色卡提取颜色再换色

流程三：参考图换色

扣费标准

创建上限