HAPI / Getting started

接入 HAPI

通过一个 API Key 使用 Claude Code、CC Switch 或 OpenAI SDK。先选择客户端,再使用与它匹配的 Base URL。

Anthropic Messages 兼容 OpenAI API 兼容 同步 / 异步生图

获取 API Key

API Key 用于识别账户、分组和用量。Claude Code 与 OpenAI SDK 使用同一类密钥,但配置字段和 Base URL 不同。

  1. 注册并登录控制台

    进入 HAPI 控制台,完成账号注册或登录。

  2. 创建 API Key

    在 API Key 页面新建密钥,并选择需要使用的模型分组。

  3. 立即妥善保存

    复制生成的完整密钥。下文统一使用 <HAPI_API_KEY> 作为占位符。

不要公开密钥。 不要把真实 API Key 放入截图、聊天记录、客户端源码或公开仓库。怀疑泄露时,请立即在控制台禁用并重新创建。

地址与协议

最常见的接入错误是给 Claude Code 的地址多写了 /v1。请按客户端选择地址,不要混用。

客户端Base URL鉴权字段实际接口
Claude Code / CC Switchhttps://hapiopen.cc
末尾不加 /v1
ANTHROPIC_AUTH_TOKEN/v1/messages
OpenAI SDKhttps://hapiopen.cc/v1api_key / Bearer/chat/completions
OpenAI Responses 客户端https://hapiopen.cc/v1api_key / Bearer/responses(完整路径 /v1/responses)
图片 APIhttps://image.hapiopen.cc/v1
推荐独立域名
Authorization: Bearer/v1/images/generations
Banana 2.1 / Gemini 原生https://hapiopen.ccAuthorization: Bearer/v1beta/models/{MODEL}:generateContent
原始 HTTP 请求https://hapiopen.ccAuthorization: Bearer填写完整接口路径
为什么不同? Claude Code 会自动在 Base URL 后请求 /v1/messages;OpenAI SDK 则要求配置已经包含 /v1 的 API 根地址。

推荐方式 · CC Switch 3.16.5

使用 CC Switch

CC Switch 适合管理多个 Claude Code 供应商。切换时它会自动写入 Claude Code 的本地配置,不需要每次手动编辑 JSON。

  1. 安装并打开 CC Switch

    从 官方 Releases 页面 下载适合当前系统的版本,安装后进入 Claude 页面。

  2. 添加 Claude 供应商

    点击添加供应商,将名称填写为 H API。供应商网站可填写 https://hapiopen.cc。

  3. 填写连接信息

    Base URL / API URL 填写 https://hapiopen.cc,API Key / Auth Token 填写控制台生成的 HAPI API Key。

  4. 保存并启用

    保存供应商,然后将 H API 设为 Claude 当前供应商。确认界面显示已切换到 H API。

  5. 重新启动 Claude Code

    关闭已经运行的 Claude Code 和旧终端窗口,重新打开终端后运行 claude 并发送一条测试消息。

Provider Name
H API
Base URL / API URL
https://hapiopen.cc,末尾不要添加 /v1
API Key / Auth Token
粘贴控制台生成的完整 HAPI API Key
模型无需在 CC Switch 中强制覆盖。 完成基础连接后,可在 Claude Code 中选择当前分组支持的模型;可用模型以 模型广场 为准。

替代方式 · Claude Code

手动修改配置

不使用 CC Switch 时,可以直接修改 Claude Code 的用户配置文件。关闭正在运行的 Claude Code 后再编辑。

Windows%USERPROFILE%\.claude\settings.json
macOS~/.claude/settings.json
Linux~/.claude/settings.json
~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<HAPI_API_KEY>",
    "ANTHROPIC_BASE_URL": "https://hapiopen.cc"
  }
}
已有配置时不要整文件覆盖。 只把上面的两个字段合并进现有 env 对象,并保留原有权限、插件、Hook 等其他设置。JSON 中不能有重复键或尾随逗号。

使配置生效

保存文件后,关闭所有 Claude Code 进程并重新打开终端。再次运行 claude,发送一条简单消息进行验证。

使用 cURL

原始 HTTP 请求适合验证 API Key 和接口连通性。下面分别测试 Anthropic Messages 与 OpenAI Chat Completions。

Claude / Anthropic Messages

cURL · Anthropic Messages
curl https://hapiopen.cc/v1/messages \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "你好"}]
  }'

Anthropic Messages 核心参数

参数必填说明
model是当前 API Key 所属分组可用的模型 ID,以模型广场为准。
messages是对话消息数组;文字可用字符串或内容块,图片输入按所选模型支持的 Anthropic 内容块格式提交。
max_tokens是本次响应允许生成的最大 Token 数,不代表一定会生成到该长度。
system否系统指令,放在顶层,不要伪装成 messages 中的 system 角色。
stream否true 返回 SSE 流,false 返回完整 JSON。
temperature / top_p / top_k否采样控制;支持范围由实际模型和上游决定,不建议同时大幅调整多个采样参数。
stop_sequences否命中指定字符串时停止生成。
tools / tool_choice否声明工具及选择策略;调用方负责执行工具并回传结果。
thinking否扩展思考配置,仅部分模型及上游支持;不支持时应删除该字段。

OpenAI Chat Completions

cURL · OpenAI
curl https://hapiopen.cc/v1/chat/completions \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "你好"}]
  }'

OpenAI Chat Completions 核心参数

参数必填说明
model是当前分组可用的准确模型 ID。
messages是对话消息数组;多模态内容、工具消息和开发者消息是否可用取决于模型与上游。
stream否true 返回流式增量,false 返回完整响应。
max_completion_tokens否限制本次输出 Token;旧客户端可能使用 max_tokens,以目标模型实际协议为准。
temperature / top_p否采样控制;推理模型可能忽略或拒绝部分采样字段。
stop否停止字符串或字符串数组;并非所有推理模型都支持。
tools / tool_choice否函数或工具调用配置,调用方负责执行工具。
response_format否结构化输出配置;模型必须具备对应 JSON 或 Schema 能力。

OpenAI Responses

POSThttps://hapiopen.cc/v1/responses
参数必填说明
model是当前分组可用的 Responses 兼容模型。
input是字符串或输入项数组,是 Responses 的主要用户输入字段。
instructions否顶层系统或开发者指令。
stream否是否以事件流返回响应。
max_output_tokens否限制最大输出 Token。
reasoning否推理配置,例如 effort;具体取值由模型决定。
tools / tool_choice否可用工具及选择方式;不同账号类型可用工具并不完全相同。
previous_response_id否仅在目标上游支持有状态响应且该响应仍可访问时使用。
cURL · OpenAI Responses
curl https://hapiopen.cc/v1/responses \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "用一句话解释什么是幂等请求",
    "max_output_tokens": 256
  }'
兼容范围由模型决定。 HAPI 提供上述协议入口,但并非每个模型都支持表中的每个可选字段。遇到 400 时先保留 model 和最小输入,确认基础调用成功后再逐项增加可选参数。

使用 Python

安装官方 OpenAI SDK:pip install openai

OPENAI BASE URLhttps://hapiopen.cc/v1
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HAPI_API_KEY"],
    base_url="https://hapiopen.cc/v1",
)

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

使用 Node.js

安装官方 OpenAI SDK:npm install openai

Node.js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.HAPI_API_KEY,
  baseURL: "https://hapiopen.cc/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "你好" }],
});

console.log(response.choices[0].message.content);

Images API

图片 API

本节只说明图片生成、图片编辑和异步任务接口。所有请求使用 HAPI API Key;可用模型以当前分组和模型广场为准。

POST · Sync

/v1/images/generations

文字生成图片。HTTP 连接会一直等待,直到图片生成成功或失败。

  • 使用 JSON 请求体
  • 支持尺寸、质量、数量和输出格式参数
  • 结果读取 data[].url 或 data[].b64_json
POST · Sync

/v1/images/edits

上传参考图进行编辑,适合保留主体、局部修改、换背景或继续加工图片。

  • 本地文件使用 multipart/form-data
  • URL 参考图可使用 JSON images[].image_url
  • 可选 mask 做局部编辑
POST · Async

/v1/images/generations/async

文字异步生图。提交后立即返回任务 ID,后台继续生成,不需要保持长连接。

  • 请求体与同步生成相同
  • HTTP 202 返回 HAPI 任务 ID
  • 按 Retry-After 查询任务
POST · Async

/v1/images/edits/async

图片异步编辑。先上传参考图创建任务,再通过任务查询端点获取最终结果。

  • 请求格式与同步编辑相同
  • 提交后由 HAPI 在后台执行
  • 提交和查询必须使用同一把 API Key
GET · Task

/v1/images/tasks/{task_id}

查询异步生图或异步编辑任务的当前状态、最终图片或失败原因。

  • processing 表示仍在生成,按 Retry-After 继续等待
  • completed 时读取 result.data[0].url
  • failed 时读取 error 和 http_status
IMAGE BASE URLhttps://image.hapiopen.cc/v1
图片 API 必须带 /v1。 主域名和独立图片域名均使用 /v1/images/*;不带 /v1 的图片 API 返回 404。OpenAI SDK 的 Base URL 填写 https://image.hapiopen.cc/v1,直接发送 HTTP 请求时使用下方完整地址。
独立域名需要 DNS 与 HTTPS 已生效。 如果暂时无法访问 image.hapiopen.cc,先使用 https://hapiopen.cc/v1/images/*。

请求头

Header必填说明
Authorization是Bearer <HAPI_API_KEY>
Content-Type是生成使用 application/json;本地图片编辑使用 multipart/form-data
以下为通用渠道接口说明;BananaRouter 接入以 GPT Image 完整参数 为准。该渠道的 mask 暂未支持,未列出 markup;不要将通用参数表理解为该渠道全部功能已开放。

GPT Images 参数适用性

能力文生图图片编辑异步任务注意事项
提示词支持支持支持使用 prompt。
多图输出使用 n使用 n沿用请求参数实际最大数量、耗时和计费由上游决定。
自定义尺寸使用 size使用 size沿用请求参数公开 API 会交给所选上游判定;站内 Image Studio 使用下方已验证范围。
质量与格式支持相关字段支持相关字段沿用请求参数不支持的选项可能由上游返回 400。
参考图-文件或 URL编辑任务可用文件使用 multipart;远程图使用 JSON。
遮罩-可选编辑任务可用遮罩能力及语义最终由上游决定。
流式预览同步生成可选不承诺不支持异步提交必须使用非流式请求。
结果格式URL 或 Base64URL 或 Base64对象存储 URL客户端按接口兼容不同返回位置。

gpt-image-2 生成与编辑完整参数

文生图、参考图编辑和遮罩编辑统一使用下表。HAPI 会按原字段转发;“上游默认”表示 HAPI 不主动补值,最终行为由所选上游账号和模型能力决定。异步提交使用相同参数,但不支持流式输出。

参数类型必填适用接口默认值 / 可选值说明
modelstring否生成、编辑gpt-image-2图片模型 ID;建议显式填写,支持情况以当前分组为准
promptstring是生成、编辑-描述主体、场景、构图、风格、光线、修改要求和需要渲染的文字
ninteger否生成、编辑1,必须大于 0输出图片数量;数量越多通常耗时和费用越高
sizestring否生成、编辑auto 或 宽x高例如 1024x1024、1536x1024;自定义值是否可用由所选上游判断
qualitystring否生成、编辑auto / low / medium / high质量越高通常耗时和费用越高;最终取值受上游限制
output_formatstring否生成、编辑png / jpeg / webp输出图片格式;省略时使用上游默认值
output_compressioninteger否生成、编辑0-100JPEG/WebP 压缩质量;PNG 不使用该参数
backgroundstring否生成、编辑auto / opaque / transparent透明背景建议配合 PNG 或 WebP;最终能力受上游限制
moderationstring否生成、编辑auto / low内容审核强度;最终仍由上游安全策略决定
stylestring否生成、编辑上游默认风格提示字段;常见上游值包括 vivid、natural,并非所有模型都支持
response_formatstring否同步生成、同步编辑url / b64_json同步客户端应兼容 URL 与 Base64;异步任务完成后统一返回对象存储 URL
streamboolean否仅同步生成falsetrue 开启流式结果;异步接口会拒绝流式请求
partial_imagesinteger否同步流式生成上游默认控制流式响应中的中间预览图数量;异步接口不支持
input_fidelitystring否仅图片编辑low / high参考图保真度;high 更重视主体和细节一致性
image / image[]file条件必填multipart 图片编辑-本地参考图;可重复传递 image 或使用 image[] 上传多张
images[].image_urlstring条件必填JSON 图片编辑-远程参考图 URL;与本地 image 二选一,不支持 file_id
maskfile否multipart 图片编辑-可选遮罩图;需要修改的区域由遮罩和 prompt 共同决定
mask.image_urlstring否JSON 图片编辑-远程遮罩图 URL;不支持 mask.file_id
参数与接口的关系。 /v1/images/generations/async 接受与同步生成相同的 JSON 参数;/v1/images/edits/async 接受与同步编辑相同的 multipart 或 JSON 参数。异步请求必须保持 stream: false。
上游能力边界。 HAPI 能识别并转发上表字段,不代表每个渠道账号都实现全部能力。模型映射后的上游如果不支持某项参数,可能忽略该字段或返回 400;先用最小请求验证,再逐项增加质量、格式、透明背景、遮罩或流式字段。

站内 Image Studio 已验证尺寸范围

下表是本站 Image Studio 为稳定性和计费档位设置的输入范围,也是直接调用 API 时的推荐范围。公开 Images API 会把其他格式的 size 交给所选上游判断;上游接受、改写或拒绝均有可能,不应把未知尺寸视为跨渠道保证。

场景或约束规则
常用正方形1024x1024、2048x2048
常用横图1536x1024、2048x1152、3840x2160
常用竖图1024x1536、2160x3840
Image Studio 最大边长宽和高都不超过 3840px
Image Studio 边长倍数宽和高都是 16px 的倍数
Image Studio 宽高比长边与短边比例不超过 3:1
Image Studio 总像素655360 至 8294400
高分辨率会更慢且更贵。 超过 2560x1440 的尺寸在本站按实验性范围展示,建议先用 quality: "low" 或较小尺寸小批量验证,再用于正式流量。

文字生成图片

cURL · Images Generations
curl https://image.hapiopen.cc/v1/images/generations \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张明亮、简洁的产品摄影图",
    "n": 1,
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "png",
    "response_format": "url"
  }'
HTTP 200 · Images Response
{
  "created": 1786181400,
  "data": [{
    "url": "https://example.com/generated.png",
    "revised_prompt": "..."
  }]
}

上传参考图编辑

cURL · Images Edits
curl https://image.hapiopen.cc/v1/images/edits \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保持主体不变,把背景改成明亮的办公空间" \
  -F "image=@input.png" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "input_fidelity=high"

多张本地参考图可重复传递 image 或使用 image[];局部编辑可额外上传 mask=@mask.png。

cURL · Images Edits with URLs
curl https://image.hapiopen.cc/v1/images/edits \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "只修改遮罩区域,把背景换成明亮的摄影棚",
    "images": [{"image_url": "https://example.com/input.png"}],
    "mask": {"image_url": "https://example.com/mask.png"},
    "size": "1536x1024",
    "quality": "high",
    "input_fidelity": "high",
    "output_format": "png"
  }'
推荐的遮罩 URL 字段是 mask.image_url。 为兼容部分 OpenAI 兼容客户端,顶层 mask_url、maskurl、maskUrl 和 mask.url 也会被 HAPI 规范化为 mask.image_url;新接入请优先使用嵌套写法。JSON 编辑的参考图必须使用 images: [{"image_url":"https://..."}];HAPI 不支持 file_id 或 mask.file_id。如果所选模型不支持远程遮罩 URL,请改用 multipart 的 mask=@mask.png。
上传文件限制。 单个 multipart 图片或遮罩文件应保持在 20 MiB 以内;请求还要同时满足入口总请求体限制。总请求体超过入口限制时会返回 413。URL 图片的大小、格式、访问权限和下载时限还受目标上游限制。

提交异步任务

cURL · Async Images
curl -i https://image.hapiopen.cc/v1/images/generations/async \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "夜晚城市中的未来感产品海报",
    "size": "1536x1024",
    "quality": "high",
    "output_format": "png"
  }'
HTTP 202 · Task Accepted
{
  "id": "imgtask_0123456789abcdef",
  "task_id": "imgtask_0123456789abcdef",
  "object": "image.generation.task",
  "status": "processing",
  "created_at": 1786096800,
  "poll_url": "/v1/images/tasks/imgtask_0123456789abcdef",
  "expires_at": 1786183200
}

查询异步任务

参数位置类型必填说明
task_idPathstring是提交异步任务时返回的 HAPI 任务 ID,例如 imgtask_0123456789abcdef
AuthorizationHeaderstring是必须使用创建任务时的同一枚 HAPI API Key
cURL · Poll Task
curl https://image.hapiopen.cc/v1/images/tasks/<TASK_ID> \
  -H "Authorization: Bearer $HAPI_API_KEY"
status是否终态处理方式
processing否读取响应头 Retry-After,默认约 3 秒后继续查询
completed是读取 result.data[].url;image_url 是第一张图片的快捷字段
failed是读取 http_status 和 error,修正参数或稍后重新提交
HTTP 200 · Completed Task
{
  "task_id": "imgtask_0123456789abcdef",
  "status": "completed",
  "http_status": 200,
  "image_url": "https://storage.example.com/images/result.png",
  "result": {
    "created": 1786096860,
    "data": [{"url": "https://storage.example.com/images/result.png"}]
  },
  "completed_at": 1786096860,
  "expires_at": 1786183260
}

Images API 常见状态码

状态码常见原因处理建议
400字段类型、尺寸、格式、模型或上游能力不匹配先退回最小请求,再逐项添加可选参数。
401API Key 缺失、无效或已禁用检查 Bearer Header,并重新创建已泄露的 Key。
403当前 Key、分组或账号没有图片权限,或被安全策略拒绝检查分组、模型权限及提示词内容。
404路径错误、模型不存在,或异步图片任务未启用核对端点;若错误明确为 async image tasks are not enabled,改用同步接口或配置对象存储。
413请求体、单个上传文件或结果超过限制压缩参考图、减少图片数量或使用 URL 输入。
429并发、速率、模型日限额或上游容量达到限制按退避策略重试,不要立即并发重放同一任务。
5xx网关、上游、下载或对象存储临时异常同步请求可稍后重试;异步请求先查询已有任务,避免重复扣费。
任务隔离。 调用方只使用 HAPI 返回的任务 ID 和查询接口。任务状态、轮询地址和内部调度细节由 HAPI 管理,不需要也不能直接访问。
  • 入口限制独立图片入口允许最大 256 MB 请求体和最长 1200 秒代理读取时间;这能减少入口提前断开,但不会缩短上游生成时间。
  • 同步结果同步结果可能位于 data[].url 或 data[].b64_json,调用方应同时兼容。
  • 异步开关异步任务依赖站点启用图片对象存储。若返回 async image tasks are not enabled,请先使用同步接口。
  • 异步结果异步完成后,HAPI 会把图片转存到站点对象存储并在 result.data[].url 返回链接;异步请求中的 response_format 不会让任务结果以大段 Base64 保存在 Redis。
  • 任务期限任务元数据在最近一次状态更新后保留 24 小时,单个任务最长执行 30 分钟。对象本身的保留时间和 URL 有效期由站点对象存储配置及存储桶生命周期规则决定。
  • 重复提交当前 HAPI 公开异步接口未开放客户端幂等键、Webhook、取消任务或自定义过期时间;网络重试可能创建新任务,请在客户端记录已返回的 task_id。
  • 异步编辑/v1/images/edits/async 是 HAPI 的后台任务接口;编辑任务会按所选模型和渠道的可用能力在后台执行。

GPT Image 2.5

Image 2.5 生图与编辑

Image 2.5 沿用 Image 2 的 OpenAI Image API 兼容接口,支持文生图、图像编辑、多参考图、局部编辑、文字渲染和自定义像素尺寸。使用对应的模型 ID,并通过 quality 选择质量档位;其他参数与 Image 2 一致。

模型选择

模型 ID定位质量选项
gpt-image-2GPT Image 2 基础模型auto、low、medium、high
gpt-image-2.5-flare速度优先,适合日常高质量图片生成auto、low、medium、high、xhigh、max
gpt-image-2.5-sunburst能力优先,适合对编辑精度要求高的场景auto、low、medium、high、xhigh、max

是否可调用任一模型,以站点模型配置、分组授权、上游可用性和上游账号权限为准。

xhigh 和 max 是 Image 2.5 新增质量档位。 适用于 gpt-image-2.5-flare 和 gpt-image-2.5-sunburst,Image 2.6 也支持这两个档位;gpt-image-2 仍只支持 auto、low、medium、high。

接口与公共参数

IMAGE BASE URLhttps://image.hapiopen.cc/v1
操作方法与路径请求格式
文字生成图片POST /v1/images/generationsapplication/json
图片编辑POST /v1/images/edits本地参考图使用 multipart;远程参考图使用 JSON
异步生成 / 编辑POST /v1/images/generations/async
POST /v1/images/edits/async
与对应同步请求一致,保持 stream: false
查询异步任务GET /v1/images/tasks/{task_id}使用提交时的同一枚 API Key

鉴权仍使用 Authorization: Bearer <HAPI_API_KEY>。主域名和独立图片域名的图片 API 均必须使用 /v1/images/*。

  • 模型与质量显式填写上述 2.5 模型 ID;quality 可选 low、medium、high、xhigh、max,也可使用 auto。省略时沿用 Image 2 的上游默认行为。
  • 其他参数prompt、n、size、格式、背景、参考图、遮罩和保真度等字段与 Image 2 完整参数 一致;质量与 input_fidelity 是不同参数,不要混用。
  • 尺寸与结果尺寸沿用 宽x高,例如 1536x1024,参考 Image 2 尺寸说明。同步结果仍读取 data[].url 或 data[].b64_json。
  • 异步任务沿用 Image 2 提交与轮询流程,替换 model 和 quality 即可;任务状态、对象存储要求、期限和错误处理保持一致。

文字生成图片:Flare + xhigh

cURL · Image 2.5 Generations
curl https://image.hapiopen.cc/v1/images/generations \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一张明亮、简洁的产品摄影图",
    "n": 1,
    "size": "1536x1024",
    "quality": "xhigh",
    "output_format": "png",
    "response_format": "url"
  }'

参考图编辑:Sunburst + max

cURL · Image 2.5 Edits
curl https://image.hapiopen.cc/v1/images/edits \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=保持主体不变,把背景改成明亮的办公空间" \
  -F "image=@input.png" \
  -F "size=1536x1024" \
  -F "quality=max" \
  -F "input_fidelity=high"

多参考图、远程图片 URL、局部遮罩和异步编辑均沿用 Image 2 的请求格式;仅替换模型名称和所需质量档位。

GPT Image API

GPT Image 完整接入

适用于本站使用 API Key 接入的 OpenAI 兼容图片渠道。模型是否可调用取决于本站模型配置、分组授权、上游状态与权限;公开 Image API 支持不等于 Codex OAuth 账号已开放同样能力。

模型与质量

模型 定位 quality
gpt-image-2 基础图片生成与编辑 auto、low、medium、high;max 兼容归一为 high
gpt-image-2.5-flare 快速迭代 auto、low、medium、high、xhigh、max
gpt-image-2.5-sunburst 精细构图与编辑 同上
gpt-image-2.6-flare 快速迭代,增加 SVG/GIF 同上
gpt-image-2.6-sunburst 精细构图,增加 SVG/GIF 同上

在工作台选择输出格式;JPEG/WebP 压缩质量、构图复杂度、内容过滤、返回方式和 SVG 作者设置位于高级参数。留空的可选字段不发送,使用上游默认;隐藏的其他格式字段不串入当前请求。SVG 作者模型留空时省略整个 svg 对象。

地址与鉴权

图片 API Base URL:https://image.hapiopen.cc/v1,主域名 https://hapiopen.cc/v1 也支持图片请求。鉴权使用 Authorization: Bearer <HAPI_API_KEY>。

用途 请求
文生图 POST /v1/images/generations,JSON
图像编辑 POST /v1/images/edits,multipart 文件或 JSON 参考图
异步任务 /v1/images/generations/async、/v1/images/edits/async,需本站启用异步图片存储

参数对照

字段 类型 / 默认 适用方式
model string,显式填写 上表模型 ID
prompt string,必填 写明主体、构图、文字与编辑要求
n integer,默认 1 图片或完整动画数量;SVG 必须 1。旧工作台每次任务固定 1
size string,默认 auto auto 或 WIDTHxHEIGHT;工作台也可选明确尺寸
quality string,默认 auto 按模型表选择,控制渲染质量
output_format string,默认 png png、jpeg、webp;2.6 另支持 svg、gif
complexity string,2.6 默认 high low、medium、high,控制构图规划复杂度;与质量、作者推理强度独立,无单独复杂度费
output_compression integer,可省略 0–100,仅 JPEG/WebP;0 必须作为有效值保留
background string,默认 auto 背景策略;gpt-image-2 不支持 transparent,其他模型以上游支持为准
moderation string,默认 auto auto 或 low
response_format string,渠道默认 b64_json 或 url,属于兼容网关扩展,不是所有 OpenAI 上游都接受的字段;本站界面只提供有效值
image / images array JSON 参考图,单复数字段等价;用于图像编辑或上游支持的参考图请求
image[] file[] multipart 编辑参考图,可重复该字段
svg object,条件需要 仅 SVG;渠道启用作者选择时传入,未启用时省略整个对象
svg.model string,传 svg 时必填 非空且上游可用的作者模型,例如 gpt-4.1-mini
svg.reasoning.effort string,可省略 作者模型支持的推理强度;不传时使用作者默认,不能冒充 complexity
frame_count integer,默认 9 GIF 专用,2–16 帧
frame_duration_ms integer,默认 200 GIF 专用,20–2000 毫秒,取整到 10 毫秒

静态位图尺寸:正整数宽高,不超过 3840,16 的倍数,长短边比不超过 3:1,总像素 655360–8294400。超过 2560×1440 的输出上游标为实验性尺寸。GIF 每帧尺寸使用正整数且为 16 的倍数,可用 512x512,不套用静态最低像素;总动画像素预算仍由模型决定,不自动缩小尺寸或减少帧数。

渠道边界

  • 该上游文档虽然在参数表列出 mask,但专节明确写“暂未支持该参数”。不能把本站其他渠道的遮罩能力当作此渠道已支持;此处不提供遮罩调用示例。
  • 该上游未列出 markup,本次不增加或宣称涂鸦标注编辑功能。
  • gpt-image-2 参考图默认按高保真处理,不传 input_fidelity 降低保真度;其他模型以对应渠道为准。
  • GIF/SVG 均不支持流式返回、partial_images 或自定义 output_compression。SVG 仅文生图、n=1,不支持 edits,也不能作为位图参考输入。
  • response_format 的 URL/Base64 转换以所选渠道能力为准;上游文档描述非法值归一为 Base64,本站客户端只发送 b64_json 或 url,不要依赖非法值。

静态图片与参考图示例

下面命令用于 Bash。先在本机设置 HAPI_API_KEY,不要将密钥写入前端代码或公开文件。

示例
curl --fail-with-body 'https://image.hapiopen.cc/v1/images/generations' \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-image-2.6-flare","prompt":"一张明亮简洁的产品摄影图","n":1,"size":"1536x1024","quality":"xhigh","complexity":"medium","output_format":"jpeg","output_compression":85,"moderation":"auto","response_format":"b64_json"}' > result.json
示例
curl --fail-with-body 'https://image.hapiopen.cc/v1/images/edits' \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -F 'model=gpt-image-2.5-sunburst' \
  -F 'image[]=@product.png' -F 'image[]=@background.png' \
  -F 'prompt=把产品放进背景,保留商标文字' \
  -F 'size=1536x1024' -F 'quality=max' -F 'output_format=webp' \
  -F 'output_compression=90' -F 'response_format=b64_json' > result.json

JSON 编辑例子(发送到同一个 /v1/images/edits):

示例
{"model":"gpt-image-2.5-sunburst","prompt":"保留主体,替换背景","images":["https://example.com/product.png","data:image/png;base64,BASE64_IMAGE_DATA"],"size":"1536x1024","quality":"high"}

image/images 数组元素支持 URL、Data URL、纯 Base64 或 {"image_url":"..."} / {"url":"..."}。URL 必须可被上游访问;私有地址、保留地址及非法协议会拒绝。上游文档中的 URL 下载单图 20MB 等限制仅适用于它的 URL 下载环节,不能套到本站所有上传路径;实际入口和文件上传限制以请求返回为准。

SVG 矢量图

仅 Image 2.6 文生图且 n=1。质量控制参考图,作者模型生成静态 XML 矢量内容;SVG 作者费用与图片渲染费用独立。响应仅在上游提供时包含 svg_usage,不将它伪装或合并为图片的 usage。

示例
curl --fail-with-body 'https://image.hapiopen.cc/v1/images/generations' \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-image-2.6-flare","prompt":"白色背景中央一个蓝色圆形,简洁矢量图标,无文字","n":1,"size":"1024x640","quality":"low","complexity":"low","output_format":"svg","response_format":"b64_json","svg":{"model":"gpt-4.1-mini"}}' > result.json

若渠道未启用作者选择,删掉整个 svg 对象;需要推理强度时可用 "svg":{"model":"支持的作者模型","reasoning":{"effort":"该模型支持的值"}}。不要为了填写示例而选择无权限模型。

示例
import base64, json
from pathlib import Path
response = json.loads(Path("result.json").read_text(encoding="utf-8"))
Path("output.svg").write_bytes(base64.b64decode(response["data"][0]["b64_json"]))

预览用图片元素显示,下载保留原始 .svg 字节和 image/svg+xml 类型,不内联执行 XML。结果要求静态矢量内容,不支持脚本、外部资源或嵌入位图。用 PNG 截图保存会失去矢量编辑能力。

返回字段与计费

字段 含义
created 响应创建时间
data[] 结果列表,GIF 每项是一个完整动画
data[].b64_json 整个文件的 Base64;按实际格式保存,不固定写 .png
data[].url 原文件 URL,按渠道选择返回
data[].revised_prompt 上游提供时返回改写后的提示词
model / output_format 上游提供时返回实际模型/格式
usage 图片渲染的文本输入、图片输入、缓存和输出等用量,字段以实际上游为准
svg_usage 上游提供时返回 SVG 作者模型用量,与图片 usage 独立

图片生成按本站渠道计费配置结算。SVG 还涉及作者模型用量,须核对渠道价格与账单;不能把未返回的 svg_usage 视作零费用。目前本站保留该元数据但不按它单独计算作者 token 费用;上游作者费用需按渠道账单核对,不能宣称本站已完整覆盖作者费用。GIF 帧数不当作独立图片数量重复计数。没有固定总价或完成时限保证。

常见错误

400 通常是参数、尺寸或参考图不符;401 为密钥;403 为分组/上游权限;404 为模型未启用;413 为体积;429 为限流/额度;5xx 为上游或服务暂时异常。先核对模型与参数,再按错误信息处理,避免不确认状态就重复提交导致重复扣费。

参考

上游 GPT Image 文档 · OpenAI 图片生成文档

GPT Image 2.6

Image 2.6 GIF 动图

使用 gpt-image-2.6-flare(快速迭代)或 gpt-image-2.6-sunburst(精细构图)生成完整 GIF 动画。请选择已配置这两个模型、使用 API Key 接入且支持 GIF 的图片渠道;是否可用以本站分组授权和上游权限为准。

在生图工作台或画布选择 Image 2.6 后,将输出格式设为“GIF 动图”,设置帧数、每帧时长与尺寸。提示词写清主体、动作、镜头和循环要求;上传静态参考图可生成动图。默认仍为 PNG。

接口与参数

IMAGE BASE URLhttps://image.hapiopen.cc/v1

文生动图使用 POST /v1/images/generations;参考图使用 POST /v1/images/edits。主域名也支持图片请求。鉴权使用本站 HAPI_API_KEY,公开 Image API 的支持不代表 Codex OAuth 账号已开放同样能力。

参数GIF 用法
output_formatgif
frame_count2–16 的整数,默认 9
frame_duration_ms20–2000 的整数,默认 200;取整到 10 毫秒
sizeauto 或正整数宽高,边长为 16 的倍数,例如 512x512;表示每帧尺寸
n完整动画数量;每个结果包含所有帧,示例为 1
qualityauto、low、medium、high、xhigh、max
response_format渠道支持的 b64_json 或 url
GIF 不使用静态图的最低总像素限制,仍受上游每帧尺寸和总像素预算约束。失败时显示错误,不自动降低帧数或缩小尺寸。GIF 不支持流式返回、partial_images 或自定义 output_compression;帧参数仅用于 GIF。

文生动图

以下为 Bash/cURL 示例,先设置本机的 HAPI_API_KEY 环境变量。

cURL · GIF generation
curl --fail-with-body 'https://image.hapiopen.cc/v1/images/generations' \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "gpt-image-2.6-flare",
  "prompt": "一只卡通小猫挥爪后回到起始姿势,固定镜头,白色背景,平滑循环动画。",
  "output_format": "gif",
  "n": 1,
  "size": "512x512",
  "quality": "medium",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "response_format": "b64_json"
}' > result.json

静态参考图生成动图

cURL · GIF edits
curl --fail-with-body 'https://image.hapiopen.cc/v1/images/edits' \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -F 'model=gpt-image-2.6-sunburst' \
  -F 'image[]=@cat.png' \
  -F 'prompt=让这只小猫挥爪后回到原姿势,固定镜头,平滑循环' \
  -F 'output_format=gif' -F 'size=512x512' \
  -F 'frame_count=9' -F 'frame_duration_ms=200' \
  -F 'response_format=b64_json' > result.json

保存完整动画

data[].b64_json 是整个 GIF 文件的 Base64 数据;上面的命令将响应保存至 result.json,再运行下方 Python 代码。返回 data[].url 时直接下载原文件并保留 .gif 后缀。

Python · Save GIF
import base64, json
from pathlib import Path

response = json.loads(Path("result.json").read_text(encoding="utf-8"))
image = response["data"][0]
Path("animation.gif").write_bytes(base64.b64decode(image["b64_json"]))

默认 9 帧 × 200 毫秒约为 1.8 秒,循环效果以生成文件为准。历史小缩略图可能只显示首帧,打开原图可播放。不要通过 Canvas 截图或 PNG/JPEG 转码保存动图,否则会丢失动画帧。浏览器本地作品请及时下载保存。

用量沿用返回的 usage 和本站渠道计费配置,动画帧不作为独立图片重复计数。模型权限、实际价格和完成时间以调用时的渠道为准。

参数参考:上游 GPT Image 文档 · OpenAI GIF 参数说明。

Gemini Native Image API

Banana 2.1 生图与编辑

使用 Gemini 原生 generateContent 格式。模型名写在请求地址中;文字与参考图放在 contents[].parts 中,文生图和图像编辑使用同一个接口。

POSThttps://hapiopen.cc/v1beta/models/gemini-nano-banana-2.1:generateContent

使用有权访问对应 Gemini 分组的 HAPI API Key,鉴权为 Authorization: Bearer <HAPI_API_KEY>。下方以 gemini-nano-banana-2.1 为示例;请从 模型广场 复制当前分组可用的准确模型名,替换地址中的模型部分。

请求协议与模型名称分别配置。 此栏目使用 Gemini 原生 JSON,不使用 /v1/images/generations、/v1/images/edits 或 OpenAI 的 messages 结构。

参数

字段取值说明
contents[].parts[].text提示词与参考图放在同一条用户消息中。
generationConfig.responseModalities["IMAGE"]请求图片输出;需要同时返回文字时可使用 ["TEXT", "IMAGE"]。
generationConfig.imageConfig.imageSize1K、2K、4K选择分辨率档位,费用以渠道对应档位定价为准。
generationConfig.imageConfig.aspectRatio1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9图片宽高比;实际像素尺寸以返回图片为准。
response_formatb64_json、url顶层扩展字段;默认 Base64 图片,url 请求图片链接。
contents[].parts[].inlineDatamimeType + data参考图 MIME 类型和不带 data URL 前缀的 Base64 内容。
contents[].parts[].fileDatamimeType + fileUri参考图 HTTP/HTTPS 链接;图片需可直接读取。

此接口不使用 GPT Image 的 quality、size、output_format 或 n。使用 imageSize 和 aspectRatio 控制图片规格。

文字生成图片

cURL · Gemini generateContent
curl https://hapiopen.cc/v1beta/models/gemini-nano-banana-2.1:generateContent \
  -H "Authorization: Bearer $HAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "一张明亮、简洁的产品摄影图"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"imageSize": "2K", "aspectRatio": "16:9"}
    },
    "response_format": "url"
  }'

参考图编辑

向同一接口发送下面的 JSON。将 <REFERENCE_IMAGE_BASE64> 替换为参考图 Base64 内容;多参考图按顺序追加多个 inlineData 部件。使用远程图片时,可把参考图部件改为 {"fileData":{"mimeType":"image/png","fileUri":"https://example.com/input.png"}}。

JSON · Gemini Image Edit
{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "保持主体不变,把背景改成明亮的办公空间"},
      {"inlineData": {"mimeType": "image/png", "data": "<REFERENCE_IMAGE_BASE64>"}}
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {"imageSize": "4K", "aspectRatio": "1:1"}
  },
  "response_format": "b64_json"
}

读取结果

遍历 candidates[].content.parts[]。图片 Base64 位于 inlineData.data,图片链接位于 fileData.fileUri;类型由对应 mimeType 标识。文字与图片可能同时出现,带 thought: true 的部件属于思考过程,不作为最终图片展示。

JSON · URL Response
{
  "candidates": [{"content": {"role": "model", "parts": [
    {"fileData": {"mimeType": "image/png", "fileUri": "https://example.com/result.png"}}
  ]}, "finishReason": "STOP"}]
}
JSON · Base64 Response
{
  "candidates": [{"content": {"role": "model", "parts": [
    {"inlineData": {"mimeType": "image/png", "data": "<IMAGE_BASE64>"}}
  ]}, "finishReason": "STOP"}]
}
  • 未生成图片HTTP 成功不一定包含图片;检查 promptFeedback.blockReason 和 finishReason。NO_IMAGE 表示没有生成图片,SAFETY 或 IMAGE_SAFETY 表示安全审核未通过。
  • 费用与重试费用以渠道按次(图片)的模型定价、尺寸档位和实际用量记录为准。等待生成结果时不要重复提交,避免产生多次请求。

验证接入

完成配置后依次检查下面几项。不要只根据 CC Switch 的“已保存”判断接口已经可用。

  • Claude Code 或调用程序已经完全重启,没有继续使用旧进程中的环境变量。
  • Claude Code 的 Base URL 是 https://hapiopen.cc,末尾没有 /v1。
  • 发送一条短消息可以获得正常回复,而不是登录提示、401 或 404。
  • 控制台用量记录中出现新的请求,模型和 API Key 与当前配置一致。
  • 需要切换模型时,从 模型广场 复制当前分组可用的准确模型名称。

常见问题

请求失败时先检查状态码,再核对 Base URL、API Key、模型名称和账户分组。

  • 401API Key 缺失、复制不完整、已被禁用,或 CC Switch 尚未启用 H API 供应商。重新粘贴密钥并完全重启客户端。
  • 404Claude Code 的 Base URL 很可能错误地写成了 https://hapiopen.cc/v1,最终形成重复路径。改为不带 /v1 的地址。
  • 400请求 JSON、接口协议或模型名称不正确。不要把 OpenAI 的请求结构发送到 Anthropic Messages 接口。
  • 429请求频率、并发或账户额度达到当前限制。降低并发并检查控制台中的余额和分组限制。
  • 模型不可用模型不属于当前 API Key 的分组,或名称已经调整。以模型广场显示的名称为准。
  • 配置未生效关闭所有 Claude Code 与终端进程,确认 CC Switch 当前供应商和 settings.json 内容,再重新启动。
  • 5xx上游模型暂时不可用。稍后重试,或切换到当前分组内的其他可用模型。
已复制到剪贴板