HiAPI
博客

教程

如何通过 HiAPI API 使用 qwen-image-2.0-pro:curl、Python 与一次可用的请求

面向开发者的动手集成演练:首次成功调用、请求结构剖析与故障排查

2026年11月17日
极简纸层叠加封面图:奶油色底上多层石墨色薄纸依次错落退进浅景深,中央一片赤陶色纸作点缀。
本页内容

qwen-image-2.0-pro 为 API 使用者提供了什么

qwen-image-2.0-pro 是一个通过 HTTP 调用的图像生成模型。从你的代码角度看,它的行为类似聊天补全端点:你发送一段描述所需图像的 JSON 载荷,然后收到一个包含生成图像的 JSON 响应。

通过 HiAPI API 访问它的优势在于一致性。一个 API 密钥、一个基础 URL、一套请求结构即可跨模型通用。如果你之后更换模型标识符或调整参数,周边代码保持不变。你无需为尝试的每个图像模型学习新的 SDK 或管理多套凭据。

本教程先用 curl 完成一次完整的首次调用,再将其移植到 Python,说明如何从响应中读出图像,最后给出排查清单和一个小巧的可复用封装。所有示例都使用相同的载荷和相同的密钥环境变量,因此终端中可用的内容在脚本中无需改动即可运行。

前置条件与密钥准备

在编写任何代码之前,请确保以下三件事已就绪。

1. HiAPI 账户与 API 密钥

创建账户并在仪表盘中生成 API 密钥。密钥是机密信息,请像对待密码一样对待它。不要将其粘贴到会提交到版本控制的源文件中。

2. 将密钥导出为环境变量

以下示例从 HIAPI_API_KEY 读取密钥,因此同样的命令和脚本在本地和 CI 中无需修改即可运行。

export HIAPI_API_KEY="your_key_here"

在 Windows PowerShell 中,使用 $env:HIAPI_API_KEY = "your_key_here"。在 CI 中,将其设置为流水线配置中的机密环境变量。

3. 用于发起 HTTP 请求的工具

curl 通常已预装。对于 Python,你需要 Python 3 和 requests 库:

pip install requests

在继续之前,你可以确认 shell 中能看到该密钥:

# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."

如果没有任何输出,说明该变量未设置,所有请求都会因认证错误而失败。请先解决这个问题。

用 curl 发起的最小可用请求

确认连通性最快的方式是执行一次 curl 调用,从环境变量读取密钥。载荷是一个 JSON 对象,包含 model 字段和聊天补全风格的 messages 数组。

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "messages": [
      {
        "role": "user",
        "content": "A small ceramic mug on a wooden table, soft morning light, product photo"
      }
    ]
  }'

这里有三个细节很重要。Authorization 头使用 Bearer 方案。model 值必须与模型标识符完全一致。content 是一个描述图像的纯字符串提示词。

如果请求成功,你会在终端看到打印出的 JSON 响应。如果失败,你会看到 HTTP 状态码和错误消息。在读取响应体前先检查状态码:401 表示密钥错误或缺失,400 通常表示载荷格式错误,而 404 或模型未找到错误表示模型标识符不正确。

一旦此命令返回成功响应,即确认连通性正常,你可以继续编写代码。

Python 中的同一请求

将调用移植到 Python 时保持载荷完全相同。唯一区别在于读取环境变量和序列化请求的方式。

import json
import os

import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "qwen-image-2.0-pro",
    "messages": [
        {
            "role": "user",
            "content": "A small ceramic mug on a wooden table, soft morning light, product photo",
        }
    ],
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))

注意 json=payload 让 requests 自动设置 Content-Type 头并序列化请求体。timeout 很重要,因为图像生成可能比典型的文本补全耗时更长;120 秒是一个合理的起点。raise_for_status() 将错误状态码转为异常,因此失败不会悄无声息。

运行此脚本,你应该得到与 curl 看到的相同 JSON。如果没有,说明你的环境与 curl 成功运行的 shell 存在差异,最常见的是密钥变量。

读取响应并处理图像输出

响应遵循聊天补全结构,因此生成图像通过与你处理文本回复相同的路径获取。先检查打印出的 JSON;其结构会很熟悉:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      }
    }
  ]
}

生成的图像出现在助手消息内容中,通常表现为 URL 或 base64 编码的载荷,具体取决于模型返回媒体的方式。不要假设是哪一种;读取该值并根据其前缀分支处理:

content = data["choices"][0]["message"]["content"]

if isinstance(content, str) and content.startswith("http"):
    image_url = content
    # Download and save if you want a local copy
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from URL")
else:
    # Treat as base64-encoded image data
    import base64

    image_bytes = base64.b64decode(content)
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from base64")

两点实用说明。如果内容是 URL,请将其视为临时链接并尽快下载,而不是在产品中直接链接它。如果是 base64,请将解码过程隔离,以便格式错误的载荷抛出可捕获的错误。在解析之前始终将原始响应写入日志文件,这样你可以在不重新运行可能很慢的请求的情况下进行调试。

失败请求的排查清单

当请求失败时,不要急于重写整个调用。按顺序执行以下检查,并在第一个失败处停止。每项检查隔离一个变量。

1. 认证

先检查状态码。401 表示密钥缺失、过期或格式错误。确认当前 shell 中已设置该环境变量,确认你使用了 Bearer 前缀,并确认头部没有尾部空格。

2. 模型标识符

模型未找到错误表示 model 值与可用模型不完全匹配。大小写和后缀都很重要。将你的值与模型文档页面逐字符比对。

3. 载荷结构

400 通常来自格式错误的请求体。确认 messages 是数组,每条消息都包含 role 和 content,且 JSON 有效。在发送前通过 jq 或 python -m json.tool 处理载荷可以捕获语法错误。

4. 响应处理

如果请求成功但脚本崩溃,问题出在解析代码而非 API。在切片之前记录原始响应体,并确认你读取的路径确实存在。图像可能在一次调用中返回 URL,在另一次返回 base64,因此请根据内容分支处理而非假设。

5. 超时与重试

图像生成可能较慢。如果遇到超时,增加客户端超时时间并重试一次。避免对 4xx 错误重试,因为它们会以相同方式再次失败。

一个有用的习惯:保存一份已知良好请求的副本,并将失败请求与之对比。大多数失败都只差一个字段。

封装为可复用客户端

一旦调用成功,将其封装在一个小函数后面,使模型和参数变更集中在一处。此封装将密钥查找、请求头和错误处理集中管理:

import base64
import os

import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"


def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
    """Generate an image and return its raw bytes."""
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
    }
    response = requests.post(
        f"{HIAPI_BASE}/chat/completions",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    content = response.json()["choices"][0]["message"]["content"]

    if isinstance(content, str) and content.startswith("http"):
        return requests.get(content, timeout=60).content
    return base64.b64decode(content)

调用代码变为一行:open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table"))。如果你之后切换到其他图像模型或添加参数,只需修改此函数。模型标识符和任何参数细节都在模型页面上,你可以先查看 qwen-image-2.0-pro 模型详情再接入。

从 curl 调用开始,然后是 Python 脚本,最后进行封装。每一步都在你构建下一层之前确认一个更小的部分。

立即开始构建持久 AI 产物

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

阅读 API 文档