博客

教程

如何通过 HiAPI API 调用 qwen-image-3.0-pro/image-to-image:curl、Python 与一次可用的请求

一份集成演练,涵盖异步任务模式、curl 与 Python 客户端,以及错误处理

2026年11月10日
封面图:错位叠放的纸页如同套印偏移的印刷品,米白纸面配炭黑边缘与一张锈红插页,右下有平直投影。
本页内容

为什么图像生图(image-to-image)是异步任务

当你调用一个图像生图模型时,你并不是在请求一个能在几百毫秒内流式返回的字符串补全结果。模型需要加载你的源图像,以它为条件运行完整的扩散式生成流程,并对输出进行编码。这可能需要几秒到几十秒不等,且时长会随分辨率和设置而变化。在整个窗口期内保持 HTTP 连接打开对各方都不划算:代理会超时,负载均衡器会丢弃空闲套接字,你自己的工作线程也会被钉在一个可能稍后仍会失败的请求上。

因此该端点采用“先提交、再轮询”模型。你的第一个请求提交一个任务,并立即返回一个任务句柄。图像生成在该句柄背后进行。随后你发起独立的、开销很低的请求来检查任务状态,直到它报告完成,此时响应会携带你所请求的结果。

这有一些实际的后果,你应该从一开始就将其纳入设计:

  • 提交不等于完成。 提交调用成功仅意味着平台接受了你的任务,仅此而已。在代码中要将这两种状态区分开来。
  • 任务 ID 是你唯一的句柄。 要持久化保存它。如果你的进程在提交与轮询之间崩溃,任务 ID 就是你无需重新提交(并再次付费)同样的工作即可恢复的依据。
  • 轮询开销低但并非免费。 状态检查很轻量,但紧凑的循环仍会产生流量,并可能触发速率限制。要拉开间隔。
  • 失败是异步到达的。 损坏的图像或被拒绝的参数可能会以任务级错误的形式出现,而不是提交时的 HTTP 错误。你的轮询代码必须读取任务状态,而不仅仅是状态码。

记住这个模型,后面的集成就会很直接:一次调用创建工作,一个循环等待它,以及对可能出错的三种情况做有意的处理。

写代码之前:需要准备什么

在接触终端之前,先收集本指南中每次调用都依赖的几样东西。

HiAPI 凭据

你需要一个 HiAPI 的 API 密钥。把它当作机密:从环境变量加载,而不是粘贴进你可能提交的脚本里。下面的示例将其读取为 HIAPI_API_KEY。API 的基础 URL 和确切的模型标识符 qwen-image-3.0-pro/image-to-image 是你全程要引用的两个常量。

一张源图像

图像生图需要输入。准备好一张,并决定如何提供它:

  • 作为可公开访问的 URL,或者
  • 作为已上传的资产或编码后的载荷,取决于端点接受哪种形式。

在编写调用之前,查阅模型的请求 schema,确认确切的字段名和可接受的源图像格式。提供端点不接受的源图像是任务被拒绝的最常见原因,而且提前排除它比从错误信息中去调试要容易得多。

一个能轮询的客户端

由于调用是异步的,你用来发送请求的工具也需要能够反复发出后续请求。curl 适合做首次冒烟测试;任何更长期的用途都应该是脚本。没有需要配置的回调 URL,也没有需要托管的 webhook——轮询就是机制,所以要规划一个循环。

一个查看结果的地方

提前决定对你来说“完成”是什么样子:一个你可以在浏览器中打开的 URL,或者你写入磁盘的字节。在开始前知道这一点,就能在集成真正可用时一目了然。

手头有了这四样东西,第一个请求就很简短了。

用 curl 发送一次可用的请求

确认你的密钥、端点和任务生命周期都能工作的最快方式,是一次两步的 curl 会话。首先提交;然后轮询。

第 1 步:提交任务

curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/source.jpg",
    "prompt": "restyle as a soft watercolor illustration"
  }'

逐项说明:

  • -X POST —— 提交是一个创建操作。
  • Authorization 头携带你的密钥。通过导出环境变量而不是内联输入,可以避免它留在 shell 历史中。
  • Content-Type: application/json —— 请求体是 JSON。
  • -d —— JSON 载荷。image 字段指向你的源图像,prompt 描述要执行的变换。参数名和可接受的选项来自模型的请求 schema;请在那里核对,而不要猜测。

提交成功的响应是一个任务对象。它会包含一个标识符——称之为任务 ID——以及一个状态字段,应表明任务已排队或正在运行。记下任务 ID;后续一切都依赖它。

第 2 步:轮询任务

export TASK_ID="<the id from the submit response>"

curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

每次调用时,读取状态字段。当它报告待处理或运行状态时,等待几秒再检查。当它报告成功时,响应包含生成的图像——通常是可获取的 URL,或编码后的数据。当它报告失败时,响应携带解释原因的错误描述。

整个生命周期就是如此:一次提交,然后状态检查直到终态。之后你构建的任何东西,都只是这两条命令的更方便版本,加上等待和错误处理。

用 Python 实现同样的调用

手工重复这两个 curl 步骤很快就会让人厌烦,而把轮询循环复制粘贴到每个脚本里,正是微妙 bug 扩散的方式。将提交和轮询的模式包装成一个可复用的函数。

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def submit_task(source_image: str, prompt: str) -> str:
    resp = requests.post(
        BASE_URL + MODEL_PATH,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": source_image, "prompt": prompt},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]


def wait_for_task(task_id: str, poll_interval: float = 3.0,
                  max_wait: float = 300.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        task = resp.json()
        status = task["status"]
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")


def generate(source_image: str, prompt: str) -> dict:
    task_id = submit_task(source_image, prompt)
    return wait_for_task(task_id)

有几处刻意的选择值得指出:

  • 将提交与等待分离。 如果提交失败,你在任何轮询发生之前就能知道。如果你以后想在一个进程中提交、在另一个进程中收集,接缝已经存在。
  • 每个请求都有 timeout。 没有超时的请求可能会无限期挂起,这正是异步 API 本应帮你避免的失败模式。
  • 轮询循环既有间隔也有整体截止时间。 没有截止时间,一个卡在运行状态的任务会永远循环。没有间隔,你会猛打端点。
  • 状态字符串是显式匹配的。 任何既不是成功也不是失败的状态都会落入下一次迭代,这对中间状态是正确的默认行为。

像调用任何函数一样调用它:generate(source_url, "make the background a dusk cityscape")。返回的对象是终态任务载荷,从中提取图像引用。

处理错误与失败的任务

异步工作流中的错误分为三类,每一类都需要不同的应对。

请求级拒绝

这些是提交调用的普通 HTTP 错误响应——凭据错误或缺失、JSON 格式错误、不支持的参数、无法访问的源图像。它们在任何任务存在之前到达。

正确的应对几乎总是停下来并呈现消息。重试格式错误的载荷只会浪费配额和时间。逐字记录状态码和响应体;验证消息通常会指出有问题的字段。有两种情况值得特别处理:认证失败应快速且响亮地失败,因为它们意味着配置问题;速率限制响应可以在退避后重试。

任务级失败

这里提交成功了,任务 ID 存在,但工作失败了。轮询响应报告失败状态并附带错误。

这一类涵盖模型自身的问题:源图像能解码但不可用、提示词被拒绝、生成触达内部限制。由于这些与输入特定相关,盲目重试通常会复现同样的失败。逐个情况决定:暂时的内部错误可能值得重试一次;被拒绝的源图像永远不值得。将任务 ID 与错误一起记录,以便与支持请求关联。

永不结束的轮询

提交成功,任务存在,轮询在运行——但终态始终不到达。这不是平台返回的错误;这是你代码中的一个假设,必须过期。

用截止时间来防护它,如 Python 示例所示。当截止时间触发时,停止轮询。不要静默返回半完成的结果;抛出或返回一个明确的超时结果,让调用方决定。保留任务 ID——任务可能仍在你的截止时间之后完成,你可能想稍后收集它而无需重新提交。

对这三类情况的实用经验法则:将任务状态视为唯一真相源。HTTP 状态码告诉你请求是否被接受;任务的状态和错误字段告诉你工作是否成功。同时读取两者,失败就变得可诊断,而不是神秘莫测。

将其包装进生产代码

上面的函数是一个可用的集成,而不是一个完成的服务。在它承载真实流量之前,要收紧四件事。

处处有超时

为每次调用设置明确的连接和读取超时——提交、轮询,以及任何对结果图像的后续获取。然后为整个任务生命周期设置整体截止时间。HTTP 层的超时保护单个请求;任务截止时间保护整个操作。

有判断力的重试

只重试可以安全重试的内容。轮询时的速率限制和暂时性网络错误符合条件。被拒绝的载荷不符合。对于任务级失败,重试意味着提交新任务,这与重试状态检查是不同且更昂贵的操作——要将其作为有意的决定,最好有上限。

包含任务 ID 的日志

在提交时以及随后的每次状态转换时记录任务 ID,连同时间信息。提交与首次终态之间的间隔是当事情感觉慢时你实际会想要的指标。当用户报告糟糕的结果时,任务 ID 是将轶事转化为可追溯记录的关键。

让轮询远离请求路径

如果你的函数运行在 Web 处理程序内,同步轮询循环会在整个生成时间内保持请求打开——这正是异步设计要避免的问题。相反,在处理程序中提交,将任务 ID 返回给调用方,并在后台工作进程、队列或计划任务中执行等待。然后客户端轮询你的服务,而不是模型。

按这个顺序构建,集成就会从“在我的机器上能用”变成你可以依赖的东西:提交,持久化句柄,带限制地等待,让任务状态——而不是希望——告诉你何时停止。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档