博客

教程

如何通过 HiAPI API 调用 muse-image-1.0/text-to-image：curl 与 Python

2026年11月3日

这个集成实际涉及什么

在 HiAPI 上，一次文本到图像的调用就是一次同步 HTTP 请求：你发送一个描述所需图像的 JSON 请求体，响应返回时包含生成的图像数据。此端点没有轮询循环或作业队列需要管理——一次请求，一次响应。

涉及的组件很少：

你的 API 密钥——通过 Authorization 头对请求进行身份验证。
端点——HiAPI 基础 URL 上 muse-image-1.0/text-to-image 的固定 URL 路径。
JSON 请求体——携带你的提示词以及模型接受的任何可选参数。
响应负载——返回生成的图像数据，由你解码或转发。

这就是全部接口面。下面的章节会用 curl 逐块构建请求，然后用 Python 重复同样的过程，这样你可以在增加复杂度之前验证每个部分。

先决条件与身份验证

在发出第一个请求之前，请确保你已具备：

一个 API 密钥，来自你的 HiAPI 账户仪表板。请像对待密码一样对待它；切勿将其提交到源代码管理中。
一个 HTTP 客户端——curl 用于测试即可；脚本版本的目标环境是 Python 3.8+。
HiAPI API 的基础 URL，你可以在仪表板文档中与密钥一起找到。

身份验证使用 Authorization 头中的 Bearer 令牌。每个发往 muse-image-1.0/text-to-image 的请求都需要它：

Authorization: Bearer $HIAPI_API_KEY

将密钥存储在环境变量中，而不是硬编码在脚本里：

export HIAPI_API_KEY="your-key-here"

此模型的端点路径是 /muse-image-1.0/text-to-image，附加在基础 URL 之后。确切的基础 URL 记录在你的 HiAPI 仪表板中；也请将其保存在环境变量中，这样你无需修改代码即可切换环境：

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

设置好这两个变量后，你就可以发送请求了。

一个可用的 curl 请求

下面是一个最小的 muse-image-1.0/text-to-image 调用。它发送一个提示词，并将原始 JSON 响应写入文件，这样你可以在编写任何解析代码之前检查它。

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

关于请求体有几点需要注意：

prompt 是必填项——它是模型渲染的文本描述。
n 是可选的，控制你请求的图像数量。省略它则接受默认值。
只包含你已在 HiAPI API 参考文档中针对此模型确认过的参数。不要猜测未文档化的字段；未知参数可能会被服务器验证拒绝或静默忽略。

如果请求成功，response.json 包含图像数据。如果失败，你会收到错误响应体和非 2xx 状态码——请参阅下面的错误处理章节。

你可以检查 HTTP 状态码而不输出整个响应体：

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

用 Python 实现同样的请求

Python 版本使用 requests，与 curl 调用完全一致——相同的端点、相同的头、相同的请求体。将其提取为一个可复用的函数。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

有两个细节值得保留：

timeout=60——设置显式超时。图像生成比典型的 JSON API 调用慢；没有超时，你的进程可能会在连接停滞时无限期挂起。
raise_for_status()——将 HTTP 错误暴露为异常，而不是让你静默地将错误响应体当作图像来解析。

如果你已经在使用 httpx 或 aiohttp，转换很直接：相同的头，相同的 JSON 请求体。此请求不依赖任何特定的 HTTP 库。

读取同步响应

由于 muse-image-1.0/text-to-image 是同步的，图像数据在同一个响应中到达——无需第二次调用来获取结果。响应是 JSON；在编写解析器之前先检查一次其结构：

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

如何处理图像取决于响应携带的内容：

如果响应包含 base64 图像数据

解码字符串并将字节写入文件：

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

如果响应包含 URL

用普通的 GET 下载它——该 URL 已被授权用于检索，所以不要把 API 密钥附加到第三方主机：

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

确切的字段名——b64_json 与 url，以及包裹它们的外层结构——定义在此模型的 HiAPI API 参考文档中。先打印一次响应，确认结构，然后据此编写代码。不要假设不同模型的结构。

在服务中，不要盲目写入本地磁盘：将字节流式传输到对象存储，或直接将它们传递給任何消费图像的地方（上传步骤、队列、对你自己的客户端的响应）。在转发之前，验证解码后的字节看起来像图像（检查魔数字节）。

处理错误码与重试

HiAPI 返回标准 HTTP 状态码。有用的分诊规则是：如果我在不改变请求的情况下再次发送，同一个请求能成功吗？

修复请求——不要重试

400 Bad Request——格式错误的 JSON 或模型不接受的参数。检查 prompt 是否存在，以及你是否没有捏造字段。修复请求体；原样重试将同样失败。
401 Unauthorized——缺少或无效的 API 密钥。验证 HIAPI_API_KEY 已设置且未被轮换。
403 Forbidden——密钥有效但无权访问此端点。检查你在仪表板中的账户访问权限。
404 Not Found——路径错误。确认端点字符串恰好是 /muse-image-1.0/text-to-image 且基础 URL 正确。
422 Unprocessable Entity——JSON 格式良好但语义无效，例如值超出范围。阅读错误消息；它通常会指出字段名。

带退避的重试

429 Too Many Requests——你正被限流。指数退避并重试；如果存在 Retry-After 头，请遵守它。
5xx 错误——服务器端故障。使用指数退避并设置上限（例如三次尝试）进行重试，然后放弃并暴露错误。

一个紧凑的重试循环：

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

失败时始终记录状态码和错误响应体。响应体中的消息会告诉你给定错误属于两个类别中的哪一个。

发布前的生产检查清单

一些习惯可以让 muse-image-1.0/text-to-image 调用在离开你的笔记本后仍然可预测：

固定请求结构。 根据 API 参考文档中记录的字段验证 JSON 请求体。如果添加参数，请先确认它受支持。
在所有地方设置超时。 生成调用和对返回图像数据的任何下载都需要显式超时。
区分错误类别。 将可重试（429、5xx）与终结性（400、401、403、404、422）失败区分开来，这样你的告警不会嘈杂，重试也不会浪费。
记录关键信息。 如果响应提供请求 ID，则记录它、状态码、延迟以及提示词的长度——如果提示词可能包含敏感文本，则不要记录提示词本身。
关注成本驱动因素。 生成按输出计费——图像数量、尺寸以及你重试的频率都会影响成本。避免重试终结性错误，并在缓存结果可行时避免重新生成。
将密钥保留在服务器端。 切勿在浏览器或移动客户端中嵌入 API 密钥直接调用端点。

有了这些，集成就是一个小的、无聊的函数，你可以从任何地方调用——这正是你想要的。有关完整的参数面和当前响应字段，请查看此模型的 HiAPI API 参考文档。

查看全部文章 →