如何使用 Recraft Creative Upscale API：curl、Python 与一次真实运行

一个 image_url 字段，1254 px 输入变回 4096 px，以及任务实际返回了什么。

2026年11月3日

TL;DR

recraft/creative-upscale 会放大图像，并重绘其纹理与细节。请求体只有一个字段 image_url。没有提示词，也没有缩放设置。
它走统一的 /v1/tasks 流程：POST 获取 taskId，轮询 GET /v1/tasks/<taskId>，从 data.output[0].url 下载。
在我们的运行中，一张 1254×1254 的 PNG 在约 60 秒后返回为 4096×4096 的 WebP，约 19.8 MB。请为等待时间和文件大小做好预算。

你需要准备什么

从控制台获取 hiapi API key，以及一个可公开访问的图像 URL。模型页面列出了输入限制：推荐 PNG，最大 20 MB，每边 256–4096 px，最大 16 MP。

如果你需要文字、logo 或产品细节保持原样，请改用 Recraft Crisp Upscale。Creative Upscale 会重绘，因此小元素可能发生变化。

最简 curl 请求

export HIAPI_KEY=sk-your-key

curl -s https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/creative-upscale",
    "input": { "image_url": "https://example.com/old-illustration.png" }
  }'

响应是一个任务句柄：

{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"},"message":"success"}

轮询它，直到 data.status 为 success：

curl -s https://www.hiapi.ai/v1/tasks/tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD \
  -H "Authorization: Bearer $HIAPI_KEY"

Python：提交、轮询、保存

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def upscale(image_url: str, out_path: str) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30, json={
        "model": "recraft/creative-upscale",
        "input": {"image_url": image_url},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        time.sleep(5)
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: keep polling the SAME taskId
        if d["status"] == "success":
            url = d["output"][0]["url"]
            with open(out_path, "wb") as f:
                f.write(requests.get(url, timeout=120).content)
            return task_id
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(f"task {task_id} still running; re-poll it, do not resubmit")

upscale("https://example.com/old-illustration.png", "upscaled.webp")

生产环境中有两个细节很重要。第一，超时后绝不要重新提交：每次提交都会创建一个新的计费任务，所以请保留 taskId 并重新轮询它。第二，立即保存文件；输出 URL 带有 expireAt，且主机是临时的。

生产环境注意事项

批量任务使用回调。 不必轮询，你可以在任务体里传入 callback: {"url": "...", "when": "final"}，让 hiapi 在任务结束时调用你。把 taskId 当作去重键。
5 秒轮询间隔就足够了。 一个任务大约需要一分钟，所以轮询更快只会增加请求。
提交前验证 URL。 平台会预先拒绝格式错误的 URL（见下文），但无法访问的 https:// URL 是另一种失败，最好由你这边用一次快速的 HEAD 请求提前捕获。

我们在一次真实运行中看到的情况

我们用模型页面上的示例输入图（一张 1254×1254 的山间小屋 PNG）执行了一次真实请求。

项目	观察结果
提交响应	`{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}`
状态序列	`handling` → `archiving` → `success`
从 `created` 到 `completed` 的时间	61 秒（1792721625 → 1792721686）
输出	一张图像，WebP，`https://temp.hiapi.ai/.../...-0.webp`，带有一个约 7 天后的 `expireAt`
输入大小	1254×1254 PNG，2.7 MB
输出大小	4096×4096 WebP，约 19.8 MB

从那次运行中值得了解的事项：

archiving 阶段还没有 output。 任务在结果被移动到存储之前，会在几次轮询中报告 completed 和 status: "archiving"。只有 status == "success" 才带有 output[0].url，所以不要在你第一次看到 completed 时间戳时就读取 URL。
结果不是干净的 2 倍。 1254 px 的输入变成了 4096 px，每边约 3.3 倍。模型页面展示了同样的配对，并且没有暴露缩放字段，所以请预计输出由模型决定，而不是由你决定。如果你需要恰好 2 倍，Crisp Upscale 是符合该约定的端点。
输出文件很大。 一张图像 19.8 MB，超过 20 MB 输入限制允许你直接再喂回去的大小，所以不要在不调整尺寸的情况下对输出链式执行第二遍。
细节是被重绘的，而不仅仅是锐化。 模型页面对这对图像自己的说明是：构图、光线和颜色基本保留，而原木、石作和栏杆被重绘，一些小的元素（例如门廊旁的一棵树）会发生变化。在替换品牌资产之前请审查输出。
错误的 URL 会快速失败。 发送 "image_url": "not-a-url" 立即返回 HTTP 400：{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}。该模式是我们唯一验证过的检查；我们没有测试 256 px 最小值或 16 MP 上限。

我们只运行了一个任务，所以 61 秒这个数字是单一样本，不是基准测试。

Creative Upscale 还是 Crisp Upscale？

两者都只接受一个 image_url，且不需要提示词。它们的区别在于对像素的处理方式以及价格。

	Creative Upscale	Crisp Upscale
模型 id	`recraft/creative-upscale`	`recraft/crisp-upscale`
行为	放大并重绘纹理与细节	将宽高翻倍，保留内容和文字
最适合	旧插画、小尺寸或低分辨率艺术图	产品照片、带文字的的海报、设计资产
价格	每张图像高得多；见定价	见 Crisp 定价文章