HiAPI
Zh
博客

教程

如何使用 grok-imagine-quality 文生图 API：curl、Python 与一次可运行的请求

2026年11月3日
如何使用 grok-imagine-quality 文生图 API：curl、Python 与一次可运行的请求

摘要

  • 这是什么：在 hiapi 上使用 grok-imagine-quality/text-to-image API 的可运行方案——通过 POST /v1/tasks 创建任务，轮询 GET /v1/tasks/<taskId>（或使用回调），从 output[0].url 下载图像。
  • schema 严格且精简：prompt（必填）、aspect_ratio（13 种比例，默认 1:1）、resolution（1k | 2k，小写，默认 1k）、output_format（jpeg | png | webp，默认 jpeg）。其他任何字段都会以 400 拒绝。
  • “Quality” 是档位，不是调节项。不存在 quality 或 rich_detail 参数——更丰富的细节、材质和光照正是这个模型变体默认提供的。如果需要廉价的批量草稿，同一端点上有其标准档位的姊妹模型 grok-imagine/text-to-image。
  • 输出 URL 带有 expireAt 截止时间——请及时下载或持久化存储。

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

目标：向 grok-imagine-quality/text-to-image 发送文本提示词，并取回一张可作主视觉的成品图像文件——先用 curl，再写成可放入任务队列的小型 Python 脚本。

你只需要一样东西：hiapi API 密钥。从你的 hiapi 控制台 获取并导出：

export HIAPI_API_KEY="sk-..."

每个请求都使用标准 bearer 头进行认证：Authorization: Bearer sk-<key>。

最小可运行请求（curl）

hiapi 上的图像生成仅支持异步。你不需要等待一个长时间 HTTP 调用；而是创建一个任务，完成后获取结果。

第 1 步——创建任务：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "哑光黑色意式浓缩咖啡机放在板岩台面上的产品主视觉，戏剧性定向光，浅景深，高端商业质感",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

模型在后台工作时，你会立即得到一个 taskId：

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

第 2 步——轮询直到进入终止状态：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

任务会经历 queued → handling → archiving，最终到达 success 或 fail。只有 success 会携带输出：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

第 3 步——在 expireAt 之前下载：

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Python 中的相同流程

一个完整的脚本——创建、轮询、保存。复制、设置 HIAPI_API_KEY、运行。

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "哑光黑色意式浓缩咖啡机放在板岩台面上的产品主视觉，"
            "戏剧性定向光，浅景深，高端商业质感"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # 小写！"2K" 会以 400 被拒绝
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # 这里的 4xx = 请求本身被拒绝
task_id = resp.json()["data"]["taskId"]
print("任务已创建:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("已保存 hero.png")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"任务失败: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving —— 继续轮询

2k 档位的生成通常在一两分钟内完成；5 秒的轮询间隔足够。

实际存在的参数

输入 schema 是严格的——未知字段会以 400 INVALID_REQUEST: additional properties not allowed 失败，而不是被静默忽略。这是好消息：拼写错误不会溜进生产环境。完整接口范围：

字段 必填 取值 默认值
input.prompt 是 自由文本 —
input.aspect_ratio 否 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2 1:1
input.resolution 否 1k, 2k（仅小写） 1k
input.output_format 否 jpeg, png, webp jpeg

在基于它构建之前，有三件事值得了解：

  • 名称中的“quality”是档位，不是参数。你可能会看到这个模型被描述为具有更丰富的细节、材质和光照——那是模型变体本身。没有可切换的 rich_detail、quality 或 style 字段。
  • 1k 和 2k 按不同档位计费。常见模式：在 1k 下反复迭代提示词，然后用胜出的提示词在 2k 下重新运行以生成最终素材。当前每张图像的价格见 hiapi 定价页。
  • 没有 n、没有 seed、没有 negative_prompt。一个任务生成一张图像。如需变体，并行提交多个任务——它们相互独立且并发排队。

生产注意事项：回调、幂等性和错误

在生产环境中优先使用回调而不是轮询。在请求体顶层（不是 input 内）传入 callback，当任务到达终止状态时 hiapi 会调用你的服务：

{
  "model": "grok-imagine-quality/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-service.example.com/hiapi/callback",
    "when": "final"
  }
}

使用 when: "final" 时，success 和 fail 都会收到通知，因此请在你这边按 taskId 去重。保留低频轮询作为回调可能丢失时的兜底——任务详情端点始终是事实来源。

使用 Idempotency-Key 让重试安全。任务创建接受 Idempotency-Key 头（最多 255 字节）。使用相同 key 重试绝不会创建重复任务——重放会返回原始 taskId：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

区分处理三种失败形态：

  1. 认证失败——HTTP 401 及 {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}。检查密钥以及它是否有权使用此模型；不要盲目重试。
  2. 无效输入——HTTP 400 及 "error_code": "INVALID_REQUEST"，消息会指出具体字段（例如 resolution: value must be one of '1k', '2k'）。修正 payload；用相同请求体重试会以同样方式失败。
  3. 任务级失败——创建调用成功，但任务以 status: "fail" 和 data.error 对象结束。重新提交前检查 error.code。

留意 expireAt。输出 URL 是临时的。任务成功后立即下载文件，或在创建时传入 storage: "persistent" 以长期保留输出。

相关页面

常见问题

grok-imagine-quality 和 grok-imagine/text-to-image 有什么区别？ 同一端点、同一请求结构、不同档位。quality 档位面向主视觉和商业素材，具有更丰富的细节和光照，按 1k/2k 分辨率档位定价；标准版 grok-imagine/text-to-image 是用于批量和构思的更快、更便宜选项。

为什么 "resolution": "2K" 返回 400？ 枚举区分大小写且为小写：1k 或 2k。大写值会以 INVALID_REQUEST 被拒绝。

可以设置 1920x1080 这样的精确像素尺寸吗？ 不能。你通过 aspect_ratio（13 个选项，从 2:1 超宽到 9:20 超高）控制形状，通过 1k/2k 档位控制清晰度。此模型没有自由形式的 size 字段。

可以在一个请求中生成多张图像吗？ 不能——没有 n 参数。请并行提交多个任务；每个任务返回自己的 taskId，并并发处理。

grok-imagine-quality 支持图生图吗？ 支持，使用单独的模型 id：grok-imagine-quality/image-to-image。其 schema 见 图生图方案——它与文生图不同。

结果 URL 的有效期是多久？ 每个 output[] 条目都有 expireAt Unix 时间戳。在该截止时间前下载，或在创建任务时使用 storage: "persistent"（或稍后提升输出）以保留它。

已排队但未完成的任务是什么样子？ GET /v1/tasks/<taskId> 返回的 status 为 queued、handling 或 archiving，尚无 output。只有 success 包含可下载输出；fail 则包含 data.error。

标签Image APIText to ImageTutorial

相关文章

查看全部文章 →

立即开始构建持久 AI 产物

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

阅读 API 文档