如何通过 hiapi API 使用 gpt-image-2-beta：参数、代码与可运行示例

gpt-image-2-beta 是 hiapi 上进入 GPT Image 2 的极简、固定定价路线：两个输入字段，一个价格，没有宽高比或质量调节项。本指南展示最小可运行示例、确切的参数结构（通过探测线上端点确认），以及它与默认的 gpt-image-2/text-to-image 路线相比如何，便于你判断何时该用哪一种。

前置条件

你需要从 hiapi 仪表盘的 API Keys 页面获取 API 密钥——密钥以 sk- 开头。当前的单图价格见 gpt-image-2-beta 模型页面和定价页面。

与 hiapi 上的每个图像模型一样，该模型运行在统一的异步任务端点上：

• POST https://api.hiapi.ai/v1/tasks ——创建生成任务
• GET https://api.hiapi.ai/v1/tasks/{taskId} ——轮询任务状态

beta 路线有何不同

gpt-image-2/text-to-image（默认路线）接受 aspect_ratio + resolution，并按分辨率档位计价（1K 为 $0.03，最高 4K 为 $0.06）。gpt-image-2-beta 将这一切压缩为统一的每图固定价 $0.02 和一个可选 size 字段——字面像素尺寸字符串，如 "1024x1024" 或 "1600x900"，不是比例。如果完全省略 size，模型会回退到自身的默认输出尺寸。

代价是：你放弃了细粒度的比例/分辨率控制，换取更低、更简单的价格。当你只需要“便宜地生成一张图”而不在意精确构图时，它很合适。

最小可运行示例（curl）

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

完成的图像位于 data.output[0].url。该 URL 带有较短的 expireAt 有效期——请立即下载并重新托管到你自己的存储上；不要在生产内容中直接链接它。

由上述 curl 调用（使用不同提示词）生成的示例图像，使用 size: "1024x1024"。

Python：创建 + 轮询 + 保存到磁盘

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

参数参考

gpt-image-2-beta 的 input 对象只接受两个字段——该结构为 additionalProperties: false，因此其他任何内容都会被直接拒绝，而不是被静默忽略。

字段	类型	是否必填	说明
prompt	string	是	要生成图像的文本描述。
size	string	否	字面像素尺寸，例如 "1024x1024"、"1600x900"。不是宽高比关键字。省略则使用模型的默认输出尺寸。

不支持的内容（以及会得到的错误）

beta 结构不接受默认 gpt-image-2/text-to-image 路线或 OpenAI Images API 使用的任何字段——aspect_ratio、resolution、quality、background、moderation、output_format、output_compression、n、user 或 style。发送其中任何一个都会立即返回 HTTP 400，例如：

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

如果你要从默认路线或 OpenAI 的 Images API 迁移代码，请先将其精简为 prompt + size，再指向 gpt-image-2-beta。

定价：beta vs 默认 vs @ext

路线	价格	控制项
gpt-image-2-beta	$0.02/图 固定	仅 size（像素尺寸）
gpt-image-2/text-to-image（默认）	$0.03（1K）/ $0.04（2K）/ $0.06（4K）	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	$0.007–$0.76，按质量 × 分辨率	16 种宽高比、质量档位

在生产中确定路线前，请查看定价页面——任何给定模型的价格都可能变化。

在 beta 路线上构建的技巧

• 把上面的字段列表视为当前约定，而非永久约定。beta 路线的结构或定价比默认路线更可能被调整——如果你在生产中依赖它，请定期重新查看模型页面。
• 由于 size 是可选的，如果你的布局依赖特定尺寸，请始终显式传入它——不要依赖当前默认值保持不变。
• 像处理任何其他 hiapi 图像模型一样处理 status: "fail"：读取 task.error.code / task.error.message，并通过退避重试，而不是假设每次失败都是暂时性的。

常见问题

gpt-image-2-beta 与 gpt-image-2/text-to-image 是同一个模型吗？ 底层是同一个 GPT Image 2 模型，但 API 路线不同——beta 路线用参数控制换取固定、更低的价格。

我可以请求特定宽高比吗？ 不能直接请求。请选择具有你所需宽:高比例的 size 字符串（例如 16:9 用 "1600x900"），而不是使用 aspect_ratio 枚举。

如果完全不传 size 会怎样？ 任务仍会成功——模型使用自身的默认输出尺寸。

相关阅读

如需显式控制宽高比和分辨率的全功能路线，请参阅如何通过 hiapi API 使用 gpt-image-2/text-to-image。准备好自己试试了吗？从 API Keys 页面获取密钥，并运行上面的 curl 示例。