使用指南
recraft/crisp-upscale 上手指南:图像放大 API 的接入要点与计费
从能力边界到按张计费,开发者如何把图像放大稳定接入生产流程
- 模型
- recraft-crisp-upscale
本页内容
crisp-upscale 解决的是什么问题
把一张已经存在但分辨率不够的图像,变成尺寸更大、边缘更清晰的版本——这就是 recraft/crisp-upscale 的职责。它属于 image-to-image(图像到图像) 类别:你给它一张图,它返回一张放大后的图。输入端没有文本提示的位置,输出类型固定为图像。
这类模型要解决的问题很具体:
- 素材尺寸不统一。用户上传的图、历史内容库里的图、第三方合作方提供的图,分辨率参差不齐,前端展示尺寸却被设计要求固定。
- 老内容需要二次利用。几年前的配图、截图、缩略图,直接放到更大的容器里会糊。
- 生成结果的收尾。任何图像生成或编辑链路的末端,都可能需要一个放大步骤来交付最终尺寸。
如果你的需求是「从一句话生成一张图」,那不属于这个模型的范围;如果你的需求是「我有一张图,想让它更大更清晰」,那它才对得上。判断标准很简单:调用前你手上是否已经有一张具体的图像文件。有,就是它;没有,先去别处解决生成问题。
对开发者而言,这种单一职责反而是好事:接口语义简单、输入输出结构稳定、失败原因更容易定位。放大是一个可以独立测试、独立回滚的环节,不会与提示词工程纠缠在一起。

能力边界:能做什么,别指望什么
把 crisp-upscale 当成一个「专职放大工」来用,预期就不会跑偏。
它能做的
- 接收一张已有图像,输出放大后的图像,属于标准的 image-to-image 变换。
- 在放大的同时改善清晰度表现,这是「crisp」这个名字所指向的方向。
- 作为流水线中的独立环节被反复调用,输入输出都是图像,不引入额外的文本状态。
- 适合批量处理同质化的素材,例如统一把某批商品图提到目标尺寸。
它不做或做不到的
- 不接受文本提示生成图像。 它不是文生图模型,输入里没有 prompt 这个角色。
- 不负责理解画面内容。 它不会替你重绘、改风格、换背景或补全缺失的主体,这类需求属于生成或编辑类模型。
- 不能凭空创造细节。 放大本质上是基于已有像素的推断,源图严重模糊、压缩伪影极重、主体本身信息不足时,放大结果也会受限。输入质量决定输出的天花板。
- 不能指定放大倍数或目标分辨率。 当前公开参数只有必填的图片公网地址
image_url,格式支持 JPEG、PNG、WEBP,单文件不超过 10MB;没有文本提示,也没有倍数或输出尺寸参数。
一个务实的判断:先用你手上最差的那批业务素材做一轮试验,而不是拿一张精修样图。如果最差的输入放出来不可接受,问题往往在输入侧而不在调用侧。

调用前要确认的输入与输出规格
接入 HiAPI.ai 的统一接口时,把下面这份清单走完再写业务代码,能省掉大部分返工。
输入侧
- 文件能否被正常解码。 先本地校验格式与完整性,损坏文件不要发出去,浪费的是你的调用次数。
- 文件是否符合输入约束。 公开约束是格式为 JPEG、PNG 或 WEBP,单文件不超过 10MB;源图过小则放大收益有限,过大则先确认体积是否超限。
- 色彩与透明通道。 公开格式是 JPEG、PNG、WEBP;带透明通道或不在此列的来源,先用样本确认输出是否符合预期。
- 文件体积。 大文件的上传耗时与超时设置要匹配,别用默认短超时去打大图。
输出侧
- 输出尺寸。 请求里不能指定目标分辨率。接入时用几张不同尺寸的源图核对「源图尺寸 → 输出尺寸」的实际表现,形成你自己的对照表,不要按某个未开放的命名档位去假定输出。
- 输出格式与体积。 放大后的文件通常更大,下游存储与带宽要提前估算。
- 清晰度的主观验收标准。 提前定义什么叫「够清晰」,否则无法判断是否达标。
参数侧
当前公开参数只有必填的 image_url。不要自行增加倍数、目标分辨率、提示词或其他未开放参数,先用这一项跑通最小请求。
一个最小验证顺序:单张小图跑通 → 换成业务里的典型图 → 换成最差质量图 → 换成最大尺寸图。四步都过,再谈批量化。

按张计费:单价怎么算
crisp-upscale 的计费口径是按张计费——一次成功调用对应一张图,对应一次计费。价格只有一档:$0.004/张。
用量怎么估算
月度费用 ≈ 月调用张数 × $0.004。真正需要管理的变量只有一个:月调用张数。它由三个因子相乘得到:
- 日均处理的业务对象数;
- 每个对象平均需要放大的图片数;
- 重试与返工带来的额外系数。
第三项最容易被忽略。失败重试、画质不满意重放、同一张图被不同流程重复处理,都会让实际张数高于业务预期。把这三项分别打点记录,费用就能按调用量来算、来管。
控制调用量的几个手段
- 去重。 同一张图(按内容哈希判断)只放大一次,结果落库复用。内容库里同一素材被多处引用的场景,这一条往往能省下可观比例。
- 先判后放。 源图尺寸已经满足展示要求就不必放大,加一道尺寸判断即可拦截无效调用。
- 批处理与异步。 非实时场景走队列,把放大从用户请求路径上摘出去,既能合并重试,也避免超时导致的重复提交。
- 分级策略。 封面、首屏等高价值位置用放大,列表缩略图直接用原图,把预算集中在看得见的地方。
- 预算护栏。 按日或按周设定调用上限并告警,防止某个循环 bug 把额度刷穿——这类事故在按张计费的模型上代价很直接。
先做一轮全量样本统计,再决定放哪些、放多少,比拍脑袋定倍数要可靠得多。
典型用法与流水线组合
放大很少单独存在,它通常是一段流水线里的一环。以下是几类适合嵌入的场景。
素材后处理
用户上传或运营上传的图片,在入库前统一过一遍放大,让内容库的尺寸基线一致。这样前端就不必为每张图单独适配,设计稿可以按固定尺寸出。
老图与低质图的修复链路
历史内容里的截图、压缩过度的配图,先做基础清理(如裁剪、格式统一),再交给 crisp-upscale 放大,最后按目标尺寸裁切交付。注意顺序:先修后放,把可修复的问题在放大之前解决。
生成之后的收尾
任何图像生成或编辑链路,都可以在末端挂一个放大环节,把中间尺寸的结果提到交付尺寸。这条链路的好处是解耦——生成模型换不换,放大环节都不用动。
流水线结构
上传 → 校验(格式、尺寸、哈希去重)→ 调用放大 → 质量抽检 → 存储 → CDN 分发。其中质量抽检可以是人工抽看,也可以只对头部素材做自动指标监控;无论哪种,都要留一个「不达标就打回」的出口。
工程上两个提醒:放大步骤要幂等(同输入同输出,结果可缓存);失败要能独立重试,不要把整条链路重跑一遍。
常见坑与验证清单
以下是接入过程中反复出现的问题,多数可以在上线前一次性规避。
常见坑
- 把它当生成模型用。 指望它补全缺失内容或改变画面,结果必然失望。能力边界要先对齐。
- 拿精修图验收。 样图很漂亮,上线后遇到线上低质素材就翻车。验收样本必须来自实际业务分布。
- 超时设置过短。 大图处理耗时更长,默认超时容易造成「其实成功了但客户端放弃」的重复计费。
- 没有去重。 同一素材被反复放大,账单增长与业务增长不成比例。
- 假定了未开放的输出档位。 请求里并不能指定输出尺寸,如果按某个命名分辨率去排版,下游可能全部要重做。
- 循环重试无上限。 失败即重试且不设上限,一次故障能烧掉一整天的预算。
上线前验证清单
- 用实际业务分布的小样本(含最差质量图)跑通全链路;
- 记录并确认输入规格与输出尺寸的实际表现;
- 核对每次调用与每次计费的对应关系,确认没有隐性的重复调用;
- 验证去重缓存命中率;
- 验证超时、重试、熔断策略;
- 建立日常预算告警与调用量看板;
- 做一次小流量灰度,对比放大前后的主观画质与下游指标,再全量切换。
放大的收益是渐进的,风险也是渐进的:小样本对比这一步做扎实,后面的大规模接入基本就是运维工作。
从一张图跑通开始,把规格、计费和去重三件事定下来,crisp-upscale 就能稳稳地成为你图像流水线里那个不声不响但一直在干活的环节。