博客

教程

如何通过 HiAPI API 调用 fibo-2.0/image-to-image:curl 与 Python 实践

2026年11月13日
封面图:错位叠放的骨白纸张与炭黑色边缘线条,夹入一张锈红色纸页,平面构图。
本页内容

fibo-2.0/image-to-image 在流水线中的定位

文生图模型从一句提示词开始,图生图模型则从你已有的图像开始。这个差异看似不大,却决定了模型在流水线中的位置:fibo-2.0/image-to-image 不再是一开始产出素材的第一步,而是改造既有图像的编辑步骤。

典型的工作流是这样的:你获取或生成一张基础图像,用描述所需改动的指令将它送入 fibo-2.0/image-to-image,再把返回结果交给后续环节——审核、合成、存储,或另一次模型调用。由于模型同时接收输入图像和提示词,它能在重绘风格、调整或改造你描述的部分的同时,保留构图、主体位置和整体结构。

何时选择图生图而非文生图

当输出需要与现有图像保持可辨识的关联时,就选图生图:在保留主体的前提下为照片重绘风格、调整光照或色彩处理、为已批准的素材生成变体,或在最终使用前清理粗糙的底图。若你手头没有起始图像、只有一段描述,则选文生图。

该接口对你的要求

这次调用是一次作业提交:你发送输入图像、提示词以及想控制的参数,API 返回一个可追踪的作业。应把这个接口看作更大链路中一个定义清晰的阶段,而非完整的编辑应用——如何准备输入图像、如何处理结果,都由你负责。

由于请求本质上是异步的,集成设计也应围绕这一点展开:提交、保存作业标识符、轮询直至作业完成,然后获取输出引用。本指南余下部分正是构建这套流程。

发送请求前的准备

首次调用前需备好三件事:凭证、对接口形态的正确理解,以及一张准备好的输入图像。

凭证

所有发往 HiAPI API 的请求都用 API 密钥认证。密钥必须保存在服务端——绝不要嵌入浏览器代码或提交到代码仓库。最干净的做法是从环境变量读取,让同一套代码在本地和部署环境中通用:

export HIAPI_API_KEY="your-api-key"

如果还没有密钥,请先在 HiAPI 账户控制台创建,再继续操作。

接口形态

该模型在 HiAPI API 中的标识为 fibo-2.0/image-to-image。所有模型调用共用同一基础 URL 和请求约定,这意味着一旦你有一个可用的调用,改用其他模型主要就是修改模型标识和载荷字段。

准备输入图像

图生图请求需要真实的图像,而不是一个你希望它能解析的 URL。事先想好如何提供:作为随请求上传的本地文件,还是 API 接受的引用;并在编写应用代码前确认格式可用。首次请求最常见的两类失败是:发送只存在于你笔记本上的路径,以及发送接口不接受格式的文件。

构建调用前的实用检查清单:

  • 该图像是你所用语言能读取的真实文件。
  • 提示词用平实语言描述想要的编辑,而不只是关键词堆砌。
  • 你清楚要传哪些参数、哪些保持默认。
  • 发起请求的环境中能找到你的 API 密钥。

这些就绪后,就可以进入请求本身。

逐行解析可用的 curl 请求

从 curl 开始。它消除了你与 HTTP 请求之间的所有抽象,一旦出错,你能确定问题在请求而非客户端库。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fibo-2.0/image-to-image",
    "prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
    "image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
    "n": 1
  }'

下面逐项说明各部分的作用。

请求行

-X POST 设置方法。URL 是 HiAPI API 基础地址加上图像生成路径。应把基础地址放在变量或配置值中,避免在多处硬编码,这样将来改动只需编辑一处。

请求头

Authorization: Bearer $HIAPI_API_KEY 携带你的凭证;shell 会展开你先前导出的环境变量,因此密钥不会以字面形式出现在命令历史中。Content-Type: application/json 告诉 API 将请求体按 JSON 解析。发送 JSON 请求体却漏掉该请求头,是导致难懂错误的常见原因。

载荷

model 标识 fibo-2.0/image-to-image。prompt 是你的指令——描述编辑,而非整张输出图像,因为输入图像已经承载了结构。image 是接口可接受的输入图像形式;若直接内嵌,即对文件内容做 base64 编码。n 控制请求的输出数量,保持默认是最安全的起点。

如果图像较大,直接嵌入 shell 命令会变得笨重。先将其编码到文件再引用,或直接改用下一节的 Python 方法——在那里读取文件并编码只需一行。

读取响应

不要假设响应中包含已完成的图像字节。运行 curl 调用并检查 JSON:你要找的是作业标识符或状态字段,以判断任务是已完成还是仍在运行。在写任何解析代码前先捕获结构,因为响应的形态决定了你如何轮询。

将请求移植到 Python

Python 让请求更易维护,并可将它封装成能在整个代码库中复用的函数。下面是同一请求实现的轻量客户端:

import base64
import os
import time

import requests

BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]


def encode_image(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")


def submit_image_edit(image_path: str, prompt: str) -> dict:
    payload = {
        "model": "fibo-2.0/image-to-image",
        "prompt": prompt,
        "image": encode_image(image_path),
        "n": 1,
    }
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

为什么采用这种结构

把 encode_image 与 submit_image_edit 分离,让文件处理和 HTTP 处理相互独立,各自更易测试。在导入时从环境读取密钥,缺失时会立即失败,而不是在若干层之后才产生 401。显式设置 timeout 可避免连接停滞导致工作进程无限挂起。

处理响应体

raise_for_status() 将 HTTP 层失败转为可捕获并附带响应体日志的异常——这远比默默把错误对象当成功解析要有用。拿到解析后的 JSON 后,记录其中包含的作业标识符,并在开发期间记录完整响应,以便看清到底有哪些字段。不要基于假设编写解析器;要基于你实际观察到的响应来写。

保持可复用

两个小改进很快就能带来回报:将基础 URL 和模型名放入常量,让其他模型调用共用该客户端;让提交函数返回类型化结构(小型 dataclass 或已知键的 dict),使轮询代码有稳定的契约可依赖。

处理异步生命周期与轮询

图像作业不是瞬时完成的。集成应将提交与完成视为两个独立事件。

步骤 1:提交并持久化

提交作业后,将作业标识符存到持久位置——数据库行、队列消息,或至少一行日志。如果进程在提交与完成之间崩溃,未记录的作业就是丢失的工作。将标识符与你系统中拥有该结果的实体绑定,以便日后对账。

步骤 2:带退避的轮询

以合理间隔轮询作业状态接口。紧循环反复轰击状态接口既浪费资源,也是最常见的异步错误:

def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        job = response.json()
        if job.get("status") in {"succeeded", "failed"}:
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

从较短间隔开始并逐步增长,既能保持早期检查的响应性,又避免长期高频请求。硬性截止时间防止对永不完成的作业无限等待。

步骤 3:把失败当作正常结果

完成的作业不一定是成功的作业。读取输出前先检查状态,并显式分支处理失败:记录作业返回的错误详情,向调用方发出可重试信号,并决定重试应复用同一输入还是重新生成。客户端侧已超时的作业可能仍在服务端运行,因此不要未经检查就盲目重新提交。

步骤 4:获取并存储结果

作业报告成功后,读取它提供的输出引用并及时下载。若要长期存储结果,请复制到你自己的存储中,而不要依赖引用永久有效。

常见错误及修复方法

大多数失败可归入几类可预测的情形。请按顺序过一遍这份清单。

身份验证失败

401 或 403 几乎总意味着请求头错误或密钥缺失。确认请求头严格为 Authorization: Bearer <key>,Bearer 后有一个空格;并确认环境变量确实设置在发起请求的进程中——而不只是你的交互式 shell 里。粘贴密钥时带尾随空白或多余引号,占了这类问题的相当大比例。

载荷格式错误

400 或 422 通常意味着 API 无法解释请求体。按顺序检查三件事:Content-Type: application/json 是否存在、JSON 是否真能解析(尾随逗号会破坏它)、必需字段是否以正确名称存在。若发送 base64 图像数据,确认它是合法 base64 且底层文件格式受支持——截断或双重编码的字符串会产生令人困惑的校验错误。

轮询错误

如果作业似乎永不完成,确认你轮询时使用的是提交响应实际返回的标识符,且读取的是正确的状态字段。忽略 failed 状态的紧循环看起来会像挂起。加入硬超时并记录观察到的状态变化;该日志通常能立刻揭示问题。

响应解析陷阱

若代码在读取结果时抛异常,不要猜测响应形态。先记录原始响应体。常见问题包括:把引用误当字节、把仅在成功时才有的字段当作始终存在、用失败路径解析器解析成功响应。基于你实际见过的响应来构建提取逻辑。

快速分诊习惯

出问题时,先隔离层级:用相同载荷运行 curl 命令。若 curl 成功而 Python 失败,错误在客户端;若两者都失败,错误在请求。这一简单测试比任何其他调试习惯都省时间。

有了可用的调用和稳健的轮询循环,fibo-2.0/image-to-image 就成为可靠的编辑步骤——从 HiAPI 的模型页面开始,将上述请求适配到你自己的图像。

立即开始构建持久 AI 产物

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

阅读 API 文档