黑白照片上色

接口标识: photocolorize 价格: 0.001 元/次 VIP免费异步响应

接口介绍
接口文档
在线测试

接口简介

黑白照片上色接口对黑白或褪色照片智能上色：还原真实自然的色彩与正常肤色，色彩过渡平滑，保持画面内容、构图与人物五官不变，可选同步增强色彩饱和度与画面通透感。输入支持JPG/JPEG/PNG/BMP/TIFF/WEBP格式，宽高1~8000px、单图最大10MB；输出锁定1k档，不传尺寸时按输入图比例自动等比缩放，也可指定输出尺寸（宽×高不超过2250000、宽高比1:8~8:1）。上色结果由平台转存、长期可下载。照片本身完好时用本接口；有划痕、噪点等破损需要修复加上色时请选老照片修复上色接口。适合老照片数字化、影楼后期与纪念馆藏数字化。【调用约定】本接口为任务类：返回的 task_id 需调用 taskresult 查询终态结果（output_status 为 finish 或 fail）；status 为 not 或 processing 时请每隔5-10秒重复查询直至终态。

详细介绍

![黑白照片上色接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261111/apiops_photocolorize__1794363411_0733e61e8339.png)

家里的黑白老照片想恢复色彩，手工上色既贵又慢。黑白照片上色接口提交照片即智能还原自然色彩，画面内容与人物五官保持不变。

## 接口概述
面向老照片数字化、影楼后期与家庭影像修复场景，提交一张黑白或褪色照片，接口对照片智能上色：还原真实自然的色彩与正常肤色，色彩过渡平滑，保持画面内容、构图与人物五官不变，还可选同步增强色彩饱和度与画面通透感。这是任务类接口，提交后先返回task_id，随后凭task_id通过taskresult接口轮询查询（也支持回调通知），output_status=finish时拿到最终结果。上色结果由平台转存，长期可下载。注意边界：照片本身完好时用本接口；有划痕、噪点等破损需要修复加上色时，请选老照片修复上色接口。

## 核心能力
1. **智能上色**：黑白与褪色照片还原自然色彩，肤色正常、色彩过渡平滑。
2. **保真约束**：保持画面内容、构图与人物五官不变，并内置负向约束抑制卡通化、人脸变形、过度磨皮等失真。
3. **增强可选**：color_enhance开启后同步提升色彩饱和度与画面通透感，颜色更鲜艳饱满。
4. **尺寸可控**：输出锁定1k档；不传size按输入图比例自动等比缩放，传入则校验宽×高不超过2250000、宽高比在1:8~8:1之间。
5. **格式广泛**：输入支持JPG/JPEG/PNG/BMP/TIFF/WEBP，宽高1~8000px，单图最大10MB。

## 产品优势
1. **接入简单**：提交即返回task_id，一个查询接口拿结果，可用自定义流水号serialnumber做幂等与查询。
2. **产物长期有效**：结果图由平台转存，不像临时链接会过期，随时可下载分发。
3. **稳定可靠**：高峰期提交自动排队调度，任务超时自动接续轮询，结果不丢失。
4. **准确规范**：上色为确定性交付，返回图片实际宽高与档位信息，便于归档管理。
5. **生态开放**：与老照片修复上色接口同一套任务协议，按照片状况选择能力、无缝组合。

## 效果展示
一句话理解：它就像一位老照片修复师，拿到黑白照片后依照画面内容一笔笔补回真实颜色，而不改动照片里的人和景。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| file | https://example.com/demo/old_photo.jpg | 待上色的黑白或褪色照片，支持公网URL、Base64、文件ID，最大10MB |
| color_enhance | true | 是否同步增强色彩饱和度与通透感，默认false |

提交后先拿到task_id，用它通过taskresult接口轮询，output_status=finish时查回最终结果。你会拿到的结果（凭 task_id 经 taskresult 查询、output_status=finish 时的异步结果）：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 任务状态 | `"finish"` | `output_status`，处理中为processing，失败为fail |
| 上色结果图地址 | https://fujian.phpwc.com/pyapi/uploads/api/20261112/pc21demo000000000000001_1762930900_e5f6a7b8.png | `output_dourl`，平台转存、长期有效 |
| 结果图地址（同值） | 同上 | `output_content`，与output_dourl同值 |
| 结果详情 | 宽1600、高1200、1k档 | `output_info`，含width、height、size_tier、color_enhance、size等 |
| 结果说明 | 照片上色完成，输出 1600x1200（1k 档），并已增强色彩饱和度。 | `output_msg` |
| 处理耗时 | `52` | `output_time`，单位秒 |

API请求示例：

```text
POST /api/photocolorize
file=https://example.com/demo/old_photo.jpg&color_enhance=true
```

API响应示例（taskresult 查回的最终结果）：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "task_id": "pc21demo000000000000001",
    "serialnumber": "",
    "jk_mark": "photocolorize",
    "output_status": "finish",
    "output_content": "https://fujian.phpwc.com/pyapi/uploads/api/20261112/pc21demo000000000000001_1762930900_e5f6a7b8.png",
    "output_dourl": "https://fujian.phpwc.com/pyapi/uploads/api/20261112/pc21demo000000000000001_1762930900_e5f6a7b8.png",
    "output_info": {
      "width": 1600,
      "height": 1200,
      "size_tier": "1k",
      "color_enhance": true,
      "size": "1600*1200"
    },
    "output_msg": "照片上色完成，输出 1600x1200（1k 档），并已增强色彩饱和度。",
    "output_time": 52
  },
  "request_id": "req-photocolorize-demo01"
}
```

output_dourl与output_content同值，都是转存后的长期有效地址；output_info里的宽高与档位来自结果图实际参数，便于归档核对。

## 应用场景
1. **家庭老照片**：长辈的黑白结婚照、全家福上色焕新，冲印留念。
2. **影楼后期**：复古风写真做黑白转彩色的批量后期处理。
3. **馆藏数字化**：纪念馆、档案馆的历史照片数字化上色展览。
4. **内容创作**：自媒体历史影像资料上色二次创作。

## 应用案例
一家影楼推出“老照片焕新”服务，此前依赖修图师手工上色，一张要半小时、旺季积压严重；接入接口后前台收片即提交，一分钟内出上色结果，修图师只做精修，交付周期大幅缩短。

一位用户想给爷爷奶奶的黑白结婚照上色作为金婚礼物，找店修复怕划伤原片；现在用手机翻拍照片提交接口，得到自然上色的电子版并冲印装框，画面细节与人物样貌保持原样。

一个地方档案馆在做历史照片数字化展陈，几百张馆藏黑白照片需要统一上色；批量提交后按返回的宽高与档位信息归档，展览筹备进度明显加快。

常见问题

Q：提交任务后怎么拿到上色结果？

A：提交成功返回task_id，凭task_id（或提交时自定义的serialnumber）调用taskresult接口轮询查询，output_status=finish时返回最终结果：output_dourl与output_content同值，为平台转存后的长期有效图片地址。建议按固定间隔查询直至完成。

Q：和老照片修复上色接口怎么选？

A：照片本身完好、只是黑白或褪色时选本接口，专注智能上色；照片有划痕、噪点、破损等问题需要修复加上色一体处理时，选老照片修复上色接口。

Q：输出图片的尺寸怎么定？

A：不传size时按输入图比例自动等比缩放并锁定1k档（宽×高不超过2250000）；也可显式指定size，格式为“宽*高”，宽高比须在1:8~8:1之间，超出限制返回参数错误。

Q：color_enhance开启后有什么不同？

A：默认false只做自然上色；开启true后在上色同时提升色彩饱和度与画面通透感，颜色更鲜艳饱满，适合希望成片更明快的场景。

照片上色老照片修复黑白照片影像数字化影楼后期 AI修图

接口地址： https://www.phpwc.cn/api/photocolorize

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`file`	string	必填	-	待上色的黑白/褪色照片，公网URL / Base64(data:开头) / 文件ID(fileid_开头)；格式 JPG/JPEG/PNG/BMP/TIFF/WEBP，宽高 1~8000px、单图不超过 10MB
`color_enhance`	bool	选填	`false`	是否同步增强色彩饱和度与画面通透感，默认 false
`size`	string	选填	-	输出尺寸，格式「宽高」如 16001200（选填）。不传由平台按输入图比例自动缩放并锁定 1k 档；v1 仅开放 1k 档，宽×高 ≤ 2250000、宽高比 1:8~8:1，超出将被本站提前拦截
`serialnumber`	string	选填	-	开发者自定义查询编号（可选，不传则无），同接口下不可重复，用于幂等控制和 taskresult 查询

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`task_id`	string	任务ID，用于通过 taskresult 接口查询任务结果
`serialnumber`	string	调用方传入的 serialnumber（未传入则为空），用于通过 taskresult 接口查询任务结果
`task_msg`	string	照片上色预计耗时约45~60秒，建议每10秒通过 taskresult 接口轮询查询一次。
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

异步响应字段（调用 taskresult 返回）

本接口为异步任务类：提交后立即返回 task_id，需再调用 taskresult（传 task_id 或 serialnumber）查询结果，返回字段如下。

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	任务结果数据
`task_id`	string	任务ID（与提交响应一致）
`serialnumber`	string	调用方传入的 serialnumber（未传则为空串）
`jk_mark`	string	原调用接口标识
`output_status`	string	任务状态：not=未开始 / processing=处理中 / finish=完成 / fail=失败
`output_content`	string	完成后的文本结果（如翻译全文、问答答案），无则为空串
`output_dourl`	string	完成后的产物下载地址（图片/文档/音视频），无则为空串
`output_info`	object	任务明细数据（随接口不同，见子字段）
`output_msg`	string	任务说明 / 状态提示文案
`output_time`	int	任务耗时（秒）
`request_id`	string	请求追踪ID

taskresult 响应 JSON 示例：

{
  "code": 0,
  "desc": "success",
  "data": {
    "task_id": "任务ID",
    "serialnumber": "调用方传入的流水号",
    "jk_mark": "photocolorize",
    "output_status": "finish",
    "output_content": "文本结果（无则空）",
    "output_dourl": "产物下载地址（无则空）",
    "output_info": { },
    "output_msg": "任务完成提示",
    "output_time": 12
  },
  "request_id": "abc123..."
}

请先登录后使用在线测试