如何使用 hiapi 的 API 提升图像分辨率：一套 4K 放大工作流

如果你有一张低分辨率的产品图、一张小小的 AI 生成缩略图，或者一份旧扫描件，需要一份清晰的 2K/4K 版本，你并不需要专门配备一个超分辨率服务。hiapi 统一的 /v1/tasks 端点让你可以对多个图像模型发起同样的请求——这些模型接受已有图像，并在更高的分辨率档位上重绘它。本方案展示了完整的可运行流程：提交任务、轮询（或接收回调）获取结果，然后下载放大后的文件。

先说一句实话：hiapi 目前（还）没有开放专门的、保持像素的超分辨率模型。这里你得到的是生成式放大——模型在更高的目标分辨率下重绘你的源图像，同时遵循一个提示词，要求它保持构图并补充细节。对于照片和插画来说，这通常就是人们所说的“提升图像分辨率”，但它并不是无损插值，所以如果你需要对比如一张带小字的截图做逐位精确的像素缩放，就不要用这个。

你将构建什么，以及需要先准备什么

你将构建一个小脚本，它会：

1. 上传一个指向你现有图像的引用（任何公开 URL 都行——你自己的 CDN、R2、S3 等）
2. 提交一个图生图任务，要求进行 4K 重绘
3. 轮询直到任务完成，并下载更高分辨率的结果

开始之前：

• 一个 hiapi 账户和一把 API 密钥，在仪表盘的 API Keys 页面创建。下面每个请求都需要 Authorization: Bearer sk-<your-key>——没有密钥就无法调用这些端点。
• 一个可公开访问的 URL，指向你想要放大的图像。hiapi 的任务工作进程会在服务端拉取图像，所以 localhost 路径或私有存储桶都不行——请先上传到任何公开主机。
• Python 3.8+ 并安装 requests（pip install requests），或者如果你更想在 shell 里测试，直接用 curl 即可。

最小可运行示例

最干净的选择是 seedream-5.0-lite/image-to-image。它的输入 schema 恰好要求四个字段——prompt、image_urls、aspect_ratio 和 resolution——而 resolution 只接受 2K 或 4K（这条路由上没有 1K 档位，这正好意味着你不会不小心让它缩小你的图像）。

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_upscale_task(source_image_url: str) -> str:
    payload = {
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
            "image_urls": [source_image_url],
            "aspect_ratio": "1:1",   # match your source image's ratio
            "resolution": "4K",
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    task_id = body["data"]["taskId"]
    return task_id

def wait_for_result(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_upscale_task("https://your-cdn.example.com/product-photo-small.jpg")
    result_url = wait_for_result(task_id)
    print("4K result:", result_url)

如果你只想看看请求长什么样，这里是用 curl 发起的等价创建任务调用：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-hiapi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
      "image_urls": ["https://your-cdn.example.com/product-photo-small.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "4K"
    }
  }'

关于这个请求，有几点值得说明：

• image_urls 是一个数组，即使这个模型只读取第一个元素。传入裸字符串而不是列表，是导致 400 的常见原因。
• 输出 URL 会过期。一旦 wait_for_result() 返回，就立刻下载字节并自行存储——不要把 hiapi 托管的链接当作你的永久资源 URL。
• 如果你的源图像不是正方形，就把 aspect_ratio 设成与它匹配（4:3、16:9、9:16、3:2、2:3 或 21:9），这样模型就不会裁剪或填充你的主体。

生产环境中的做法

规模化时优先用回调而不是轮询。如果你要放大的图像不止几张，就不要为每个任务在循环里猛敲 GET /v1/tasks/<id>——传一个 callback 对象，让 hiapi 把结果推送给你：

payload = {
    "model": "seedream-5.0-lite/image-to-image",
    "input": {...},
    "callback": {
        "url": "https://your-service.example.com/hooks/hiapi-task",
        "when": "final",
    },
}

你的 webhook 会收到与轮询相同的任务对象（status、output、error）——要防御性地校验它的结构，因为网络重试可能把它投递不止一次。

在你这边为每个任务准备一个利于幂等的键。任务 API 目前不接受客户端提供的幂等键，所以如果你的任务运行器可能重试失败的 HTTP 调用，请在提交重复任务之前检查是否已经为该源图像存过 taskId——否则你这边一次短暂的超时，就可能变成同一个文件两次计费的放大。

处理两种截然不同的错误形态。格式错误的请求体会返回 HTTP 400，并带一个扁平的 {"code": 400, "error_code": "INVALID_REQUEST", "message": "..."}。API 密钥缺失或错误会返回 HTTP 401，并带一个嵌套的 {"error": {"code": "permission_denied", "message": "..."}}。先检查状态码，再分支处理：

if resp.status_code == 401:
    raise RuntimeError(f"auth error: {resp.json()['error']['message']}")
if resp.status_code == 400:
    raise RuntimeError(f"bad request: {resp.json()['message']}")
resp.raise_for_status()

根据你手头有什么输入来选择模型。下面三条路由都在同一个 /v1/tasks 端点上——只有 model 字符串和 input 字段不同：

你拥有	模型	必填输入字段
一张已有图像，想要干净的 2K/4K 重绘	seedream-5.0-lite/image-to-image	prompt、image_urls、aspect_ratio、resolution（2K|4K）
一张已有图像，想要在质量与成本之间取舍	gpt-image-2/image-to-image@ext	prompt、image_urls、quality（low|medium|high）、resolution（1K|2K|4K）
没有源图像——从文本描述生成全新的高分辨率资源	wan2.7-image/text-to-image	prompt（外加可选的 resolution 和 aspect_ratio）

注意第二行上的 @ext 后缀——它是基础 gpt-image-2 模型上的一个路由变体（hiapi 会在不止一条路由下以略有不同的定价/质量档位开放某些模型），而不是一个独立的模型系列。其中每一个每次请求的确切费用取决于你选择的分辨率和质量档位，所以请查看定价页面上的当前数字，而不要在预算逻辑里硬编码数值。

提交前先校验。这三个模型都会直接拒绝未知的输入字段（additional properties 'x' not allowed），而不是静默忽略，而且像 resolution 和 aspect_ratio 这样的枚举字段对大小写和取值都很敏感。如果你在构建封装层，请在客户端按上面的精确枚举值做校验，这样拼写错误能快速失败，而不是白白消耗一次请求。

相关阅读

• Wan 2.7 Image — 文生图 API，仅凭提示词生成全新的高分辨率图像。
• GPT Image 2 API，上表中使用的、按质量/分辨率分档的替代方案。
• hiapi API 定价，查看每个模型和档位当前的每次请求费用。
• hiapi 文档，获取完整的任务生命周期参考，包括所有回调选项。

常见问题

hiapi 有专门的图像放大器或超分辨率模型吗？ 没有专门的保持像素的模型。上面的工作流使用通用图生图模型，在更高的分辨率档位上重新生成你的图像，这对照片和插画效果很好，但不是无损放大。

我能在不改变图像内容的情况下提升分辨率吗？ 你可以通过提示模型精确保持构图、颜色和主体（“同一张图像，不要改变构图，不要增删元素，只增加细节和锐度”）来做到非常接近，但由于这是生成式重绘而非插值，细纹理上相比真正的无损放大器，仍会出现细微差异。

我能生成的最大分辨率是多少？ 上面三个模型的上限都是 4K 分辨率档位。如果你需要比这更大的尺寸，你需要对源图像分块、分别放大各区块，或者在 API 调用之后加一步客户端缩放。

试用这个需要 API 密钥吗？ 需要——每个 /v1/tasks 调用都要求 Authorization: Bearer sk-<your-key>。创建任务没有无需密钥的沙箱；请先从仪表盘获取一把密钥。

我能批量放大一整个文件夹的图像吗？ 可以——遍历你的图像 URL，每张图像提交一个任务，然后要么轮询每个 taskId，要么（在量大时更好）注册一个回调 URL，用在创建每个任务时存储的 taskId 把结果匹配回你的任务。

为什么我的请求会以“additional properties not allowed”失败？ 你发送了模型 schema 不认识的字段——例如用 size 而不是 resolution + aspect_ratio，或者从其他模型的示例里抄来了一个多余的参数。请查看上面的必填字段表，了解每个模型接受的确切字段名。