HyperAPI 使用文档

HyperAPI Codex 简明使用指南

这份文档用于帮助你在 Windows、Mac 或 Linux 电脑上，通过 HyperAPI 配置并使用 Codex CLI。

准备工作

使用 Codex CLI 前，请先准备好：

• 已安装 Node.js
• 已在 HyperAPI 网站创建 API 密钥
• Codex CLI 配置脚本中填写的 API 地址：https://hyperapi.cc

API 地址应该怎么填

运行本文中的一键配置脚本时，按提示填写：

https://hyperapi.cc

不要在脚本提示里手动加 /v1。脚本会自动处理，并在 ~/.codex/config.toml 中写入：

base_url = "https://hyperapi.cc/v1"

也就是说：

• 配置脚本里输入：https://hyperapi.cc
• Codex 最终使用的 base_url：https://hyperapi.cc/v1

Windows 电脑使用 Codex

1. 打开 PowerShell

在 Windows 电脑上打开 PowerShell 终端。

2. 安装 Codex CLI

运行下面的命令安装 Codex：

npm i -g @openai/codex

3. 检查是否安装成功

安装完成后，运行：

codex --version

如果终端能输出 Codex 版本号，说明安装成功。

4. 一键设置 Codex CLI 配置

在 PowerShell 中运行：

iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.ps1')

配置过程中按提示填写：

• API 地址：填写 https://hyperapi.cc，不要手动加 /v1
• API 密钥：填写你在 HyperAPI 网站创建的密钥

5. 开始使用 Codex

配置完成后，在终端运行：

codex

即可开始使用 Codex 聊天、写代码或处理项目。

Mac 电脑使用 Codex

1. 打开终端

在 Mac 上打开系统自带的终端。

2. 安装 Codex CLI

运行下面的命令安装 Codex：

npm install -g @openai/codex

3. 检查是否安装成功

安装完成后，运行：

codex --version

如果终端能输出 Codex 版本号，说明安装成功。

4. 一键设置 Codex CLI 配置

在终端运行：

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

配置过程中按提示填写：

• API 地址：填写 https://hyperapi.cc，不要手动加 /v1
• API 密钥：填写你在 HyperAPI 网站创建的密钥

5. 开始使用 Codex

配置完成后，在任意目录运行：

codex

即可开始使用 Codex。

Linux 电脑使用 Codex

Linux 的使用方式和 Mac 类似：

npm install -g @openai/codex
codex --version
curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
codex

配置时填写：

• API 地址：填写 https://hyperapi.cc，不要手动加 /v1
• API 密钥：填写你在 HyperAPI 网站创建的密钥

常见问题

运行 npm 提示命令不存在

说明电脑可能还没有安装 Node.js。请先安装 Node.js，再重新运行安装 Codex 的命令。

运行 codex --version 没有输出版本号

可以重新安装 Codex：

npm install -g @openai/codex

Windows 用户也可以运行：

npm i -g @openai/codex

API 地址应该填什么

如果你运行本文中的 Codex CLI 一键配置脚本，填写：

https://hyperapi.cc

脚本会自动把 Codex 的 base_url 配置成：

https://hyperapi.cc/v1

如果你不是运行一键配置脚本，而是在代码、OpenAI SDK 或其他客户端里手动填写 base_url，通常应填写：

https://hyperapi.cc/v1

API 密钥在哪里获取

在 HyperAPI 网站创建密钥后，将创建好的密钥复制到配置脚本提示的位置。

使用流程总结

1. 安装 Node.js
2. 安装 Codex CLI
3. 运行 codex --version 检查安装
4. 运行一键配置脚本
5. 脚本中填写 API 地址 https://hyperapi.cc 和 API 密钥
6. 运行 codex 开始使用

HyperAPI gpt-image-2 图片模型使用指南

这份文档用于帮助开发者通过 HyperAPI 调用 gpt-image-2 模型，完成图片生成和图片编辑。

重要说明

1. HyperAPI 目前只提供 gpt-image-2 模型，不提供任何文生图工具、网页生图工具或第三方生图客户端。你需要通过 API 调用模型。
2. 如果你使用第三方生图工具，请务必创建临时 API Key。测试或使用结束后，可以在 HyperAPI 控制台删除这个临时 Key，避免长期暴露。
3. 请保护好自己的 API Key，不要把 Key 发给他人，不要提交到公开代码仓库，也不要写进前端页面、截图、日志或聊天记录。
4. 请合理使用生图功能，遵守 OpenAI 的使用规范和相关法律法规，不要生成违法、侵权、欺诈、骚扰、暴力或其他不当内容。

OpenAI 使用规范可参考：https://openai.com/policies/usage-policies/

基础配置

HyperAPI 提供 OpenAI 兼容接口。调用图片模型时使用：

Base URL: https://hyperapi.cc/v1
Model: gpt-image-2

Python 示例需要安装 OpenAI SDK：

pip install openai

下面的 Python 示例中，请把：

API_KEY = "填写你自己的 HyperAPI API Key"

替换成你在 HyperAPI 控制台创建的 API Key。

图片生成 API

图片生成用于根据文本提示词创建新图片。

POST https://hyperapi.cc/v1/images/generations
Authorization: Bearer 你的 HyperAPI API Key
Content-Type: application/json

常用参数：

Python 示例：生成图片

这个示例参考了仓库中的 test_image_generate.py，运行成功后会在当前目录生成 generated.png。

import base64
from pathlib import Path

from openai import OpenAI


API_KEY = "填写你自己的 HyperAPI API Key"
BASE_URL = "https://hyperapi.cc/v1"
MODEL = "gpt-image-2"

client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL,
)

result = client.images.generate(
    model=MODEL,
    prompt=(
        "一张写实风格的产品海报：透明玻璃茶壶放在木桌上，"
        "背景是清晨阳光照进来的现代厨房，画面干净，高级，细节丰富"
    ),
    size="1024x1024",
    response_format="b64_json",
)

image_b64 = result.data[0].b64_json
if not image_b64:
    raise RuntimeError("Image generation did not return base64 data.")

Path("generated.png").write_bytes(base64.b64decode(image_b64))
print("Saved generated.png")

图片编辑 API

图片编辑用于基于已有图片进行修改，例如替换材质、调整风格、增加元素或移除元素。编辑接口需要上传原始图片文件。

POST https://hyperapi.cc/v1/images/edits
Authorization: Bearer 你的 HyperAPI API Key
Content-Type: multipart/form-data

常用参数：

Python 示例：编辑图片

这个示例参考了仓库中的 test_image_generate_edit.py。示例会读取当前目录下的 generated.png，你可以先运行上面的生成图片示例，也可以把自己的图片命名为 generated.png。

运行成功后，会在当前目录生成 edited.png。

import base64
from pathlib import Path

from openai import OpenAI


API_KEY = "填写你自己的 HyperAPI API Key"
BASE_URL = "https://hyperapi.cc/v1"
MODEL = "gpt-image-2"

input_image_path = Path("generated.png")
if not input_image_path.exists():
    raise FileNotFoundError("Input image not found: generated.png")

client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL,
)

with input_image_path.open("rb") as image_file:
    edited = client.images.edit(
        model=MODEL,
        image=image_file,
        prompt=(
            "保持原图构图和主体不变，把茶壶改成深绿色磨砂玻璃材质，"
            "并在桌面上增加一小盘柠檬片，整体风格依然干净高级"
        ),
        size="1024x1024",
        response_format="b64_json",
    )

edited_b64 = edited.data[0].b64_json
if not edited_b64:
    raise RuntimeError("Image editing did not return base64 data.")

Path("edited.png").write_bytes(base64.b64decode(edited_b64))
print("Saved edited.png")

提示词建议

图片生成时，提示词可以包含：

• 主体：图片里最重要的人、物体或场景。
• 风格：写实、摄影、插画、产品海报、电影感等。
• 构图：近景、俯拍、居中、对称、留白等。
• 光线：清晨自然光、柔和棚拍光、霓虹灯、逆光等。
• 细节：材质、颜色、背景、氛围、是否需要出现文字等。

图片编辑时，建议明确写出：

• 哪些内容必须保持不变。
• 哪些内容需要替换、增加、删除或调整。
• 输出风格是否需要延续原图。

API Key 安全建议

如果你需要在第三方工具中测试图片功能，建议按以下方式操作：

1. 在 HyperAPI 控制台新建一个临时 API Key。
2. 只把这个临时 Key 填入第三方工具。
3. 测试完成后，到控制台删除这个临时 Key。
4. 不要把长期使用的主 Key 填入不熟悉、不可信或来源不明的工具。

如果你怀疑 API Key 已经泄露，请立即删除旧 Key，并重新创建新的 Key。

常见问题

HyperAPI 是否提供文生图工具？

不提供。HyperAPI 目前只提供 gpt-image-2 模型的 API 接口，不提供任何文生图工具、网页生图工具或第三方生图客户端。

模型名应该怎么填？

固定填写：

gpt-image-2

API 地址应该怎么填？

如果你使用 OpenAI SDK，请填写：

https://hyperapi.cc/v1

可以把 API Key 写在代码里吗？

文档中的示例为了方便新手理解，直接把 API Key 写在代码变量里。实际开发时，请确认代码不会被提交到公开仓库，也不要把包含 API Key 的代码发给别人。