如何通过 HiAPI API 调用 grok-imagine/image-to-image：curl 与 Python 指南

grok-imagine/image-to-image 为开发者提供的能力

grok-imagine/image-to-image 是一个图像变换端点：你向它提供一张参考图像和一段提示词，它会返回一张遵循提示词、同时在视觉上保持与参考图像关联的新图像。可以把它理解为引导式生成，而不是从零生成。你在 HiAPI 上调用的模型 id 就是 grok-imagine/image-to-image，请求中的其余部分都是为了描述你想要的改动。

只要输出必须保留现有素材中的某些内容——需要更换背景的产品照片、需要渲染的角色草图、需要改换风格的构图——就应选择此端点而非文本生图调用。文本生图适用于你没有源图像、只有描述的场景；image-to-image 则适用于源图像本身就是规格一部分的场景。

由于 HiAPI 将其作为单一统一接口暴露，你的集成工作仅限于构建一种请求结构并处理一种响应结构。你无需为每个模型系列引入单独的 SDK，也无需为每个端点重新学习认证方式。

请求剖析：模型、参考图像与提示词

每个有效调用在概念上都包含四个部分。在编写代码前把每一项都弄对，可以省去后续大部分调试工作。

模型 id

model 字段携带字符串 grok-imagine/image-to-image。请将其视为客户端中的一个常量，而不是散落在代码库各处的硬编码字面量——如果日后要尝试其他 HiAPI 模型，你会希望只有一个地方可以修改。

参考图像

参考图像是锚点。如何提供它取决于你选择的传输方式：可以是 API 可抓取的 URL，也可以是内联 base64 数据，适用于即时生成或无法公网访问的图像。对于你已经托管的素材，优先使用 URL；对于尚未持久化到任何公开位置的用户上传，优先使用内联数据。无论采用哪种传输方式，都要在发送之前校验图像：格式受支持、大小非零、尺寸足够有意义。

提示词

提示词描述的是变换，而不是整个场景。如果参考图像中已经包含主体，请描述应当改变的内容——风格、光照、背景、材质——并让不变的部分保持隐含。过度指定参考图像中已经可见的内容，往往会与图像条件化相冲突，而不是有所帮助。

宽高比处理

剩下的部分是输出尺寸如何决定，这是下一节的主题。在构建请求的代码中将这四个部分分开，以便各自独立校验和记录日志。

使用 auto aspect 选项

auto aspect 选项让 API 替你选择输出尺寸，而不是由你固定显式的宽度和高度。启用后，服务会根据请求上下文——最重要的是参考图像——推导出合适的宽高比，使输出的形状相对于你的输入更合理，而不是被强制放入默认画幅。

这比听起来更重要。如果你固定的尺寸与参考图像的比例不一致，就会得到类似信箱模式的伪影、主体被尴尬裁切，或构图忽略源图像取景。auto aspect 通过让几何形状跟随输入，避免了这类不匹配。

何时保持 auto 开启

• 参考图像来自用户，形状各异。
• 你正在做原型，尚不清楚哪种尺寸适合该用例。
• 输出会进入下游反正要裁剪或缩放的流水线。

何时显式固定尺寸

• 你在 UI 或印刷目标中有固定槽位，需要精确的输出几何形状。
• 你正在生成一批必须在尺寸上视觉一致的图像。

一个实用的做法是：开发时保持 auto aspect 启用，检查 API 针对真实输入返回的尺寸，然后再决定是否为生产环境锁定尺寸。将返回的图像元数据与请求一起记录，使这一决定基于证据而非猜测。

可用的 curl 请求

下面的请求除占位符外是完整的，占位符用尖括号标出。替换为你自己的值后即可直接运行。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

需要替换的占位符

• $HIAPI_API_KEY —— 从环境变量读取你的密钥，而不是将其粘贴到命令中。如果变量未设置，请求会以认证错误失败，密钥也永远不会落入你的 shell 历史记录。
• <describe the transformation you want> —— 简短、具体的指令，例如风格或背景更改。
• <publicly reachable URL of your reference image> —— 服务无需认证即可抓取的 URL。如果你的素材是私有的，请改用内联 base64 数据。

读取响应

首次运行时将输出通过 JSON 格式化工具处理，以便清晰查看响应结构。要关注两件事：图像负载（取决于响应模式，可能是 URL 或编码数据）以及调用以异步方式处理时的任务标识符。开发期间将完整的原始响应保存在日志中——当某些地方看起来不对时，这是回答"实际返回了什么"的最快方式。

同样的请求在 Python 中

Python 版本应逐字段对应 curl 请求。保持两者对齐的价值在于：在一个版本中复现的 bug 可以在另一个版本中确认，而无需猜测翻译。

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

错误处理应放在哪里

包装调用，而不是调用方。response.raise_for_status() 将非 2xx 响应转换为异常，因此围绕 generate_from_reference 的单个 try/except 可以同时覆盖传输失败和 API 拒绝。如果你想要对失败原因进行结构化日志记录，请在抛出异常之前在函数内部检查 response.status_code 和错误正文。

保持客户端整洁

在启动时读取一次 API 密钥，设置显式超时，并返回解析后的 JSON 而不是原始响应对象。调用方不应需要了解 HTTP 细节。在测试中，将 API_URL 指向一个桩服务器，这样无需花费真实生成调用即可验证请求构建逻辑。

同步与异步响应

某些 image-to-image 请求完成得足够快，可以在同一个 HTTP 响应中返回结果。其他请求则作为作业处理：初始调用返回标识符，图像稍后可用。你的客户端不应假设是其中任何一种。

如何区分二者

每次调用后检查响应正文。如果它直接包含图像负载，就处于同步路径——提取并返回它。如果它包含的是作业或任务标识符，就处于异步路径，必须轮询直到作业达到终止状态。

为两者进行结构设计

一个小的分发函数可将两条路径挡在业务逻辑之外：

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

避免麻烦的轮询规则

• 使用带上限的指数退避，而不是紧密循环。
• 设置最大总等待时间，并在超过时干净地失败。
• 将每个非终止状态视为"继续等待"，只有两种状态是最终状态：成功和失败。
• 在每次轮询时记录作业 id，以便仅凭日志就能追踪卡住的作业。

分发方式意味着在同步和异步行为之间切换时，调用 resolve_result 的代码永远无需更改。

调试常见错误码

此端点上大多数失败的调用都归入少数几类。按顺序逐项检查以下清单——它从最常见的原因排到最少见的原因。

认证失败

如果响应表明存在认证问题，说明密钥缺失、格式错误或未发送。检查执行调用的进程中环境变量是否确实已填充，以及头部是否严格为 Authorization: Bearer <key>。密钥在你的 shell 中有效但在服务中无效，通常意味着服务的环境与你的 shell 环境不同。

参考图像校验错误

与图像相关的拒绝通常意味着四种情况之一：URL 无法公开抓取、格式不受支持、负载过大，或图像太小或损坏。在浏览器中不带凭证测试该 URL——如果那里加载不了，API 也无法抓取它。对于内联 base64，请确认编码是纯 base64，且没有 data-URL 前缀（除非参数期望如此）。

提示词与参数错误

空的或过大的提示词，或未知的参数值，会产生校验响应。将你发送的确切负载与错误一起记录——相当一部分失败是字段名拼写错误，而不是值的问题。

速率限制

速率限制响应意味着退避，而不是立即重试。遵循响应头中的重试指引，加入抖动，并限制重试次数。不带退避的重试会将临时限制变成持续限制。

服务器端错误

5xx 响应属于服务端。带退避地进行有限次数的重试；如果持续存在，从响应中捕获请求 id 和时间戳，并在调查期间降低并发。

上线前的生产环境检查清单

可用的请求只是开始，而不是结束。在此端点处理真实流量之前，请确认以下各项。

在边界处校验输入

在请求离开你的服务之前，检查参考图像格式和大小、提示词长度以及参数值。本地拒绝不良输入比往返一次更快、更便宜，并且能为用户产生更清晰的错误消息。

只重试可安全重试的请求

对传输失败、速率限制和 5xx 响应使用指数退避和抖动进行重试。不要重试校验或认证错误——它们会以相同方式失败，只会增加负载。

记录足够信息以重建失败

记录模型 id、提示词的哈希或截断形式、参考图像标识符（而非完整负载）、响应状态、作业 id（如存在）以及请求 id。这组信息通常足以回答"发生了什么"，而无需存储敏感内容。

将密钥排除在代码之外

从环境或密钥管理器读取 API 密钥，绝不从源代码中的字面量读取。定期轮换密钥，若怀疑泄露则立即吊销。

关注成本行为

此端点的计费由生成驱动，因此关键杠杆是请求量、重试和轮询频率。避免重试风暴，对轮询进行退避，并对同一变换被反复请求的场景按提示词和参考图像缓存结果。查看 HiAPI 定价面板了解当前费率，而不是硬编码假设。

测试不顺利的路径

为无效图像 URL、速率限制响应和永不完成的异步作业编写测试。这三者覆盖了最有可能未被察觉地进入生产环境的失败。

有了请求构建、响应分发和错误处理，grok-imagine/image-to-image 将成为你流水线中的常规部分，而不是特殊情况。