教程
如何通过 HiAPI API 使用 qwen-image-2.0-pro:curl、Python 与一次可用的请求
面向开发者的动手集成演练:首次成功调用、请求结构剖析与故障排查
本页内容
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 脚本,最后进行封装。每一步都在你构建下一层之前确认一个更小的部分。