DeOldify服务API接口文档与调用示例（Python/Node.js）

DeOldify服务API接口文档与调用示例Python/Node.js想给你的老照片上色但又不想自己折腾复杂的模型部署和GPU环境DeOldify服务API提供了一个简单直接的解决方案。你只需要几行代码就能把黑白照片变成彩色整个过程就像调用一个普通的网络服务一样简单。这篇文章就是为你准备的“接口说明书”和“快速上手指南”。我会把每个接口怎么用、参数怎么填、返回结果怎么看都掰开揉碎了讲清楚。无论你是用Python还是Node.js都能找到可以直接复制粘贴的代码示例让你在十分钟内就能把老照片修复功能集成到自己的应用里。1. 服务概述与核心概念DeOldify是一个基于深度学习的图像着色模型它能让黑白照片、老电影画面恢复色彩。而我们今天要聊的是它的API服务版本。你可以把它想象成一个在云端24小时运转的“老照片修复工厂”。你不需要关心工厂里有多少台机器、用的是什么型号的GPU你只需要知道怎么把照片送进去以及怎么把修好的照片取出来。这个“送”和“取”的过程就是通过我们下面要讲的几个API接口完成的。整个流程非常简单主要分三步上传图片把你要修复的黑白照片发给服务端。查询进度服务端开始处理你可以时不时问一下“修好了没”。获取结果处理完成后下载修复好的彩色图片。整个过程是异步的。也就是说你上传图片后服务器会告诉你“收到啦正在处理这是你的任务号”然后你就可以先去忙别的过一会儿再用这个任务号来问结果。这样设计的好处是即使修复一张高分辨率照片需要几十秒你的程序也不会傻等着可以同时处理其他逻辑。2. API接口详细说明我们先把所有接口的“地址”定下来。假设你的DeOldify API服务部署在https://api.your-deoldify-service.com请替换成你实际的服务地址。所有接口都以其为根路径。2.1 上传图片接口这是整个流程的起点。你需要把黑白图片文件发送给服务器服务器会创建一个修复任务。接口地址:POST /api/v1/tasksContent-Type:multipart/form-data请求参数:参数名类型是否必填说明imageFile是要修复的图片文件。支持常见的格式如JPG、PNG等。render_factorInteger否渲染因子影响着色效果和细节。值越大色彩越鲜艳但可能引入更多伪影值越小色彩越保守。通常范围在15-40之间默认值由服务端设定例如35。返回格式 (JSON):{ code: 200, msg: success, data: { task_id: 550e8400-e29b-41d4-a716-446655440000 } }状态码说明:200: 任务创建成功返回唯一的task_id。400: 请求参数错误例如未上传图片文件或图片格式不支持。413: 上传的图片文件过大。500: 服务器内部错误。关键点请务必保存好返回的task_id它是后续查询任务状态和获取结果的唯一凭证。2.2 查询任务状态接口上传图片后你可以用这个接口来检查任务的处理进度。接口地址:GET /api/v1/tasks/{task_id}请求参数:路径参数:task_id- 上传接口返回的任务ID。返回格式 (JSON):{ code: 200, msg: success, data: { task_id: 550e8400-e29b-41d4-a716-446655440000, status: processing, progress: 65 } }状态码说明:200: 查询成功返回任务当前状态。404: 指定的task_id不存在。500: 服务器内部错误。任务状态 (status) 说明:pending: 任务已接收排队等待处理。processing: 任务正在处理中。progress字段可能表示处理进度百分比。success: 任务处理成功彩色图片已就绪。failed: 任务处理失败。此时可以查看msg字段获取失败原因。2.3 获取处理结果接口当任务状态变为success时你可以调用此接口下载修复后的彩色图片。接口地址:GET /api/v1/tasks/{task_id}/result请求参数:路径参数:task_id- 上传接口返回的任务ID。返回格式:成功时直接返回图片的二进制流并设置Content-Type为image/jpeg或image/png。失败时返回JSON格式的错误信息。状态码说明:200: 成功响应体为修复后的图片。404: 指定的task_id不存在或任务尚未成功。410: 任务结果已过期或被清理如果服务端设置了结果保存时限。500: 服务器内部错误。3. Python调用示例我们用最常用的requests库来实现。如果你还没安装在命令行里运行pip install requests就行。下面的代码展示了一个完整的流程上传图片、轮询状态、下载结果。import requests import time import json # 1. 配置API服务的基础地址 BASE_URL https://api.your-deoldify-service.com # 请替换为你的实际服务地址 def upload_image(image_path, render_factor35): 上传黑白图片创建修复任务 url f{BASE_URL}/api/v1/tasks files {image: open(image_path, rb)} data {render_factor: render_factor} if render_factor else {} try: response requests.post(url, filesfiles, datadata) response.raise_for_status() # 如果状态码不是200抛出异常 result response.json() if result.get(code) 200: task_id result[data][task_id] print(f任务创建成功任务ID: {task_id}) return task_id else: print(f任务创建失败: {result.get(msg)}) return None except requests.exceptions.RequestException as e: print(f请求出错: {e}) return None except json.JSONDecodeError: print(响应不是有效的JSON格式) return None def check_task_status(task_id): 查询指定任务的状态 url f{BASE_URL}/api/v1/tasks/{task_id} try: response requests.get(url) response.raise_for_status() result response.json() if result.get(code) 200: status_info result[data] print(f任务状态: {status_info[status]}, 进度: {status_info.get(progress, N/A)}%) return status_info else: print(f状态查询失败: {result.get(msg)}) return None except requests.exceptions.RequestException as e: print(f状态查询请求出错: {e}) return None def download_result(task_id, save_pathcolored_image.jpg): 下载处理成功的彩色图片 url f{BASE_URL}/api/v1/tasks/{task_id}/result try: response requests.get(url) # 检查是否返回图片根据Content-Type或状态码 if response.status_code 200 and image in response.headers.get(Content-Type, ): with open(save_path, wb) as f: f.write(response.content) print(f图片已成功下载并保存至: {save_path}) return True else: # 可能是错误信息JSON格式 error_info response.json() print(f下载失败: {error_info.get(msg, 未知错误)}) return False except requests.exceptions.RequestException as e: print(f下载请求出错: {e}) return False def main(): 主函数演示完整调用流程 # 替换为你的黑白图片路径 old_image_path ./old_photo.jpg # 第一步上传图片 task_id upload_image(old_image_path, render_factor30) if not task_id: print(流程终止于上传阶段。) return # 第二步轮询任务状态直到完成或失败 max_retries 30 # 最大轮询次数 poll_interval 5 # 每次轮询间隔秒 for i in range(max_retries): status_info check_task_status(task_id) if not status_info: break current_status status_info[status] if current_status success: print(任务处理成功开始下载结果...) # 第三步下载结果 download_result(task_id, save_pathf./colored_{task_id[:8]}.jpg) break elif current_status failed: print(f任务处理失败: {status_info.get(msg, 无详细原因)}) break elif current_status in [pending, processing]: print(f任务处理中... ({i1}/{max_retries}) {poll_interval}秒后再次查询。) if i max_retries - 1: # 最后一次循环不需要sleep time.sleep(poll_interval) else: print(f未知状态: {current_status}) break else: print(f轮询超过{max_retries}次任务仍未完成请稍后手动查询任务ID: {task_id}) if __name__ __main__: main()这段代码的逻辑很清晰。upload_image函数负责发送图片并拿到任务号。check_task_status函数就像个侦察兵每隔几秒去问一下“活儿干完了没”。一旦侦察兵回报说“干完了”状态是successdownload_result函数就出动去把修好的彩色图片搬回来保存到本地。你可以根据自己的需要调整轮询的次数和间隔时间。4. Node.js调用示例对于Node.js环境我们使用axios库来处理HTTP请求。首先在你的项目目录下安装它npm install axios。以下是完整的Node.js调用示例使用了ES Module语法。import axios from axios; import fs from fs/promises; import { createReadStream } from fs; import FormData from form-data; // 需要安装: npm install form-data // 1. 配置API服务的基础地址 const BASE_URL https://api.your-deoldify-service.com; // 请替换为你的实际服务地址 /** * 上传黑白图片创建修复任务 * param {string} imagePath - 本地图片路径 * param {number} [renderFactor35] - 渲染因子 * returns {Promisestring|null} 任务ID */ async function uploadImage(imagePath, renderFactor 35) { const url ${BASE_URL}/api/v1/tasks; const formData new FormData(); // 添加图片文件 formData.append(image, createReadStream(imagePath)); // 添加可选参数 if (renderFactor) { formData.append(render_factor, renderFactor.toString()); } try { const response await axios.post(url, formData, { headers: formData.getHeaders(), }); if (response.data.code 200) { const taskId response.data.data.task_id; console.log(任务创建成功任务ID: ${taskId}); return taskId; } else { console.log(任务创建失败: ${response.data.msg}); return null; } } catch (error) { console.error(上传请求出错:, error.message); if (error.response) { console.error(服务器响应错误:, error.response.data); } return null; } } /** * 查询指定任务的状态 * param {string} taskId - 任务ID * returns {Promiseobject|null} 任务状态信息 */ async function checkTaskStatus(taskId) { const url ${BASE_URL}/api/v1/tasks/${taskId}; try { const response await axios.get(url); if (response.data.code 200) { const statusInfo response.data.data; console.log(任务状态: ${statusInfo.status}, 进度: ${statusInfo.progress || N/A}%); return statusInfo; } else { console.log(状态查询失败: ${response.data.msg}); return null; } } catch (error) { console.error(状态查询请求出错:, error.message); return null; } } /** * 下载处理成功的彩色图片 * param {string} taskId - 任务ID * param {string} [savePathcolored_image.jpg] - 保存路径 * returns {Promiseboolean} 是否成功 */ async function downloadResult(taskId, savePath colored_image.jpg) { const url ${BASE_URL}/api/v1/tasks/${taskId}/result; try { const response await axios.get(url, { responseType: arraybuffer, // 重要指定响应数据为二进制Buffer }); // 检查Content-Type判断是否为图片 const contentType response.headers[content-type]; if (response.status 200 contentType contentType.startsWith(image/)) { await fs.writeFile(savePath, Buffer.from(response.data)); console.log(图片已成功下载并保存至: ${savePath}); return true; } else { // 尝试解析为JSON错误信息 try { const errorData JSON.parse(Buffer.from(response.data).toString()); console.log(下载失败: ${errorData.msg || 未知错误}); } catch { console.log(下载失败: 服务器返回未知格式); } return false; } } catch (error) { console.error(下载请求出错:, error.message); return false; } } /** * 主函数演示完整调用流程 */ async function main() { // 替换为你的黑白图片路径 const oldImagePath ./old_photo.jpg; // 第一步上传图片 const taskId await uploadImage(oldImagePath, 30); if (!taskId) { console.log(流程终止于上传阶段。); return; } // 第二步轮询任务状态 const maxRetries 30; const pollInterval 5000; // 毫秒 for (let i 0; i maxRetries; i) { const statusInfo await checkTaskStatus(taskId); if (!statusInfo) { break; } const currentStatus statusInfo.status; if (currentStatus success) { console.log(任务处理成功开始下载结果...); // 第三步下载结果 const savePath ./colored_${taskId.substring(0, 8)}.jpg; await downloadResult(taskId, savePath); break; } else if (currentStatus failed) { console.log(任务处理失败: ${statusInfo.msg || 无详细原因}); break; } else if (currentStatus pending || currentStatus processing) { console.log(任务处理中... (${i 1}/${maxRetries}) ${pollInterval / 1000}秒后再次查询。); if (i maxRetries - 1) { await new Promise(resolve setTimeout(resolve, pollInterval)); } } else { console.log(未知状态: ${currentStatus}); break; } } } // 执行主函数 main().catch(console.error);Node.js版本的逻辑和Python版完全一致。需要注意的是上传文件时我们用了form-data库来构建表单下载图片时设置了responseType: arraybuffer来正确接收二进制数据。代码里加了详细的注释你应该能轻松看懂每一步在做什么。5. 总结把DeOldify这样的AI能力通过API封装起来确实大大降低了使用门槛。你不需要成为深度学习专家也不用准备昂贵的显卡只需要会写基本的网络请求代码就能给老照片赋予新的色彩。上面的文档和代码示例已经覆盖了从上传到下载的全流程。在实际集成时你主要需要做两件事一是把代码里的API基础地址换成你自己服务的真实地址二是根据你的业务逻辑调整错误处理和状态轮询的策略。比如对于Web应用你可能需要把轮询放在前端或者用WebSocket来接收处理完成的通知。代码中的render_factor参数值得多尝试几次不同的值对最终效果影响挺明显的。对于人物肖像可能低一点的值如20-25肤色会更自然对于风景照高一点的值如35-40能让色彩更鲜明。多试几张图你就能找到感觉了。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。