/v1/images/generations
文字生成图片。HTTP 连接会一直等待,直到图片生成成功或失败。
- 使用 JSON 请求体
- 支持尺寸、质量、数量和输出格式参数
- 结果读取
data[].url或data[].b64_json
HAPI / Getting started
通过一个 API Key 使用 Claude Code、CC Switch 或 OpenAI SDK。先选择客户端,再使用与它匹配的 Base URL。
API Key 用于识别账户、分组和用量。Claude Code 与 OpenAI SDK 使用同一类密钥,但配置字段和 Base URL 不同。
进入 HAPI 控制台,完成账号注册或登录。
在 API Key 页面新建密钥,并选择需要使用的模型分组。
复制生成的完整密钥。下文统一使用 <HAPI_API_KEY> 作为占位符。
最常见的接入错误是给 Claude Code 的地址多写了 /v1。请按客户端选择地址,不要混用。
| 客户端 | Base URL | 鉴权字段 | 实际接口 |
|---|---|---|---|
| Claude Code / CC Switch | https://hapiopen.cc末尾不加 /v1 | ANTHROPIC_AUTH_TOKEN | /v1/messages |
| OpenAI SDK | https://hapiopen.cc/v1 | api_key / Bearer | /chat/completions |
| OpenAI Responses 客户端 | https://hapiopen.cc/v1 | api_key / Bearer | /responses(完整路径 /v1/responses) |
| 图片 API | https://image.hapiopen.cc/v1推荐独立域名 | Authorization: Bearer | /v1/images/generations |
| Banana 2.1 / Gemini 原生 | https://hapiopen.cc | Authorization: Bearer | /v1beta/models/{MODEL}:generateContent |
| 原始 HTTP 请求 | https://hapiopen.cc | Authorization: Bearer | 填写完整接口路径 |
/v1/messages;OpenAI SDK 则要求配置已经包含 /v1 的 API 根地址。推荐方式 · CC Switch 3.16.5
CC Switch 适合管理多个 Claude Code 供应商。切换时它会自动写入 Claude Code 的本地配置,不需要每次手动编辑 JSON。
从 官方 Releases 页面 下载适合当前系统的版本,安装后进入 Claude 页面。
点击添加供应商,将名称填写为 H API。供应商网站可填写 https://hapiopen.cc。
Base URL / API URL 填写 https://hapiopen.cc,API Key / Auth Token 填写控制台生成的 HAPI API Key。
保存供应商,然后将 H API 设为 Claude 当前供应商。确认界面显示已切换到 H API。
关闭已经运行的 Claude Code 和旧终端窗口,重新打开终端后运行 claude 并发送一条测试消息。
H APIhttps://hapiopen.cc,末尾不要添加 /v1替代方式 · Claude Code
不使用 CC Switch 时,可以直接修改 Claude Code 的用户配置文件。关闭正在运行的 Claude Code 后再编辑。
%USERPROFILE%\.claude\settings.json~/.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,发送一条简单消息进行验证。
原始 HTTP 请求适合验证 API Key 和接口连通性。下面分别测试 Anthropic Messages 与 OpenAI Chat Completions。
curl \ -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": "你好"}] }'
| 参数 | 必填 | 说明 |
|---|---|---|
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 | 否 | 扩展思考配置,仅部分模型及上游支持;不支持时应删除该字段。 |
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": "你好"}] }'
| 参数 | 必填 | 说明 |
|---|---|---|
model | 是 | 当前分组可用的准确模型 ID。 |
messages | 是 | 对话消息数组;多模态内容、工具消息和开发者消息是否可用取决于模型与上游。 |
stream | 否 | true 返回流式增量,false 返回完整响应。 |
max_completion_tokens | 否 | 限制本次输出 Token;旧客户端可能使用 max_tokens,以目标模型实际协议为准。 |
temperature / top_p | 否 | 采样控制;推理模型可能忽略或拒绝部分采样字段。 |
stop | 否 | 停止字符串或字符串数组;并非所有推理模型都支持。 |
tools / tool_choice | 否 | 函数或工具调用配置,调用方负责执行工具。 |
response_format | 否 | 结构化输出配置;模型必须具备对应 JSON 或 Schema 能力。 |
https://hapiopen.cc/v1/responses| 参数 | 必填 | 说明 |
|---|---|---|
model | 是 | 当前分组可用的 Responses 兼容模型。 |
input | 是 | 字符串或输入项数组,是 Responses 的主要用户输入字段。 |
instructions | 否 | 顶层系统或开发者指令。 |
stream | 否 | 是否以事件流返回响应。 |
max_output_tokens | 否 | 限制最大输出 Token。 |
reasoning | 否 | 推理配置,例如 effort;具体取值由模型决定。 |
tools / tool_choice | 否 | 可用工具及选择方式;不同账号类型可用工具并不完全相同。 |
previous_response_id | 否 | 仅在目标上游支持有状态响应且该响应仍可访问时使用。 |
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 }'
model 和最小输入,确认基础调用成功后再逐项增加可选参数。安装官方 OpenAI SDK:pip install openai
https://hapiopen.cc/v1import 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)
安装官方 OpenAI SDK:npm install openai
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
本节只说明图片生成、图片编辑和异步任务接口。所有请求使用 HAPI API Key;可用模型以当前分组和模型广场为准。
文字生成图片。HTTP 连接会一直等待,直到图片生成成功或失败。
data[].url 或 data[].b64_json上传参考图进行编辑,适合保留主体、局部修改、换背景或继续加工图片。
multipart/form-dataimages[].image_urlmask 做局部编辑文字异步生图。提交后立即返回任务 ID,后台继续生成,不需要保持长连接。
Retry-After 查询任务图片异步编辑。先上传参考图创建任务,再通过任务查询端点获取最终结果。
查询异步生图或异步编辑任务的当前状态、最终图片或失败原因。
processing 表示仍在生成,按 Retry-After 继续等待completed 时读取 result.data[0].urlfailed 时读取 error 和 http_statushttps://image.hapiopen.cc/v1/v1/images/*;不带 /v1 的图片 API 返回 404。OpenAI SDK 的 Base URL 填写 https://image.hapiopen.cc/v1,直接发送 HTTP 请求时使用下方完整地址。image.hapiopen.cc,先使用 https://hapiopen.cc/v1/images/*。| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <HAPI_API_KEY> |
Content-Type | 是 | 生成使用 application/json;本地图片编辑使用 multipart/form-data |
| 能力 | 文生图 | 图片编辑 | 异步任务 | 注意事项 |
|---|---|---|---|---|
| 提示词 | 支持 | 支持 | 支持 | 使用 prompt。 |
| 多图输出 | 使用 n | 使用 n | 沿用请求参数 | 实际最大数量、耗时和计费由上游决定。 |
| 自定义尺寸 | 使用 size | 使用 size | 沿用请求参数 | 公开 API 会交给所选上游判定;站内 Image Studio 使用下方已验证范围。 |
| 质量与格式 | 支持相关字段 | 支持相关字段 | 沿用请求参数 | 不支持的选项可能由上游返回 400。 |
| 参考图 | - | 文件或 URL | 编辑任务可用 | 文件使用 multipart;远程图使用 JSON。 |
| 遮罩 | - | 可选 | 编辑任务可用 | 遮罩能力及语义最终由上游决定。 |
| 流式预览 | 同步生成可选 | 不承诺 | 不支持 | 异步提交必须使用非流式请求。 |
| 结果格式 | URL 或 Base64 | URL 或 Base64 | 对象存储 URL | 客户端按接口兼容不同返回位置。 |
gpt-image-2 生成与编辑完整参数文生图、参考图编辑和遮罩编辑统一使用下表。HAPI 会按原字段转发;“上游默认”表示 HAPI 不主动补值,最终行为由所选上游账号和模型能力决定。异步提交使用相同参数,但不支持流式输出。
| 参数 | 类型 | 必填 | 适用接口 | 默认值 / 可选值 | 说明 |
|---|---|---|---|---|---|
model | string | 否 | 生成、编辑 | gpt-image-2 | 图片模型 ID;建议显式填写,支持情况以当前分组为准 |
prompt | string | 是 | 生成、编辑 | - | 描述主体、场景、构图、风格、光线、修改要求和需要渲染的文字 |
n | integer | 否 | 生成、编辑 | 1,必须大于 0 | 输出图片数量;数量越多通常耗时和费用越高 |
size | string | 否 | 生成、编辑 | auto 或 宽x高 | 例如 1024x1024、1536x1024;自定义值是否可用由所选上游判断 |
quality | string | 否 | 生成、编辑 | auto / low / medium / high | 质量越高通常耗时和费用越高;最终取值受上游限制 |
output_format | string | 否 | 生成、编辑 | png / jpeg / webp | 输出图片格式;省略时使用上游默认值 |
output_compression | integer | 否 | 生成、编辑 | 0-100 | JPEG/WebP 压缩质量;PNG 不使用该参数 |
background | string | 否 | 生成、编辑 | auto / opaque / transparent | 透明背景建议配合 PNG 或 WebP;最终能力受上游限制 |
moderation | string | 否 | 生成、编辑 | auto / low | 内容审核强度;最终仍由上游安全策略决定 |
style | string | 否 | 生成、编辑 | 上游默认 | 风格提示字段;常见上游值包括 vivid、natural,并非所有模型都支持 |
response_format | string | 否 | 同步生成、同步编辑 | url / b64_json | 同步客户端应兼容 URL 与 Base64;异步任务完成后统一返回对象存储 URL |
stream | boolean | 否 | 仅同步生成 | false | true 开启流式结果;异步接口会拒绝流式请求 |
partial_images | integer | 否 | 同步流式生成 | 上游默认 | 控制流式响应中的中间预览图数量;异步接口不支持 |
input_fidelity | string | 否 | 仅图片编辑 | low / high | 参考图保真度;high 更重视主体和细节一致性 |
image / image[] | file | 条件必填 | multipart 图片编辑 | - | 本地参考图;可重复传递 image 或使用 image[] 上传多张 |
images[].image_url | string | 条件必填 | JSON 图片编辑 | - | 远程参考图 URL;与本地 image 二选一,不支持 file_id |
mask | file | 否 | multipart 图片编辑 | - | 可选遮罩图;需要修改的区域由遮罩和 prompt 共同决定 |
mask.image_url | string | 否 | JSON 图片编辑 | - | 远程遮罩图 URL;不支持 mask.file_id |
/v1/images/generations/async 接受与同步生成相同的 JSON 参数;/v1/images/edits/async 接受与同步编辑相同的 multipart 或 JSON 参数。异步请求必须保持 stream: false。下表是本站 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 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" }'
{
"created": 1786181400,
"data": [{
"url": "https://example.com/generated.png",
"revised_prompt": "..."
}]
}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 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" }'
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。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" }'
{
"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_id | Path | string | 是 | 提交异步任务时返回的 HAPI 任务 ID,例如 imgtask_0123456789abcdef |
Authorization | Header | string | 是 | 必须使用创建任务时的同一枚 HAPI API Key |
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,修正参数或稍后重新提交 |
{
"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
}| 状态码 | 常见原因 | 处理建议 |
|---|---|---|
400 | 字段类型、尺寸、格式、模型或上游能力不匹配 | 先退回最小请求,再逐项添加可选参数。 |
401 | API Key 缺失、无效或已禁用 | 检查 Bearer Header,并重新创建已泄露的 Key。 |
403 | 当前 Key、分组或账号没有图片权限,或被安全策略拒绝 | 检查分组、模型权限及提示词内容。 |
404 | 路径错误、模型不存在,或异步图片任务未启用 | 核对端点;若错误明确为 async image tasks are not enabled,改用同步接口或配置对象存储。 |
413 | 请求体、单个上传文件或结果超过限制 | 压缩参考图、减少图片数量或使用 URL 输入。 |
429 | 并发、速率、模型日限额或上游容量达到限制 | 按退避策略重试,不要立即并发重放同一任务。 |
5xx | 网关、上游、下载或对象存储临时异常 | 同步请求可稍后重试;异步请求先查询已有任务,避免重复扣费。 |
data[].url 或 data[].b64_json,调用方应同时兼容。async image tasks are not enabled,请先使用同步接口。result.data[].url 返回链接;异步请求中的 response_format 不会让任务结果以大段 Base64 保存在 Redis。task_id。/v1/images/edits/async 是 HAPI 的后台任务接口;编辑任务会按所选模型和渠道的可用能力在后台执行。GPT Image 2.5
Image 2.5 沿用 Image 2 的 OpenAI Image API 兼容接口,支持文生图、图像编辑、多参考图、局部编辑、文字渲染和自定义像素尺寸。使用对应的模型 ID,并通过 quality 选择质量档位;其他参数与 Image 2 一致。
| 模型 ID | 定位 | 质量选项 |
|---|---|---|
gpt-image-2 | GPT 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。https://image.hapiopen.cc/v1| 操作 | 方法与路径 | 请求格式 |
|---|---|---|
| 文字生成图片 | POST /v1/images/generations | application/json |
| 图片编辑 | POST /v1/images/edits | 本地参考图使用 multipart;远程参考图使用 JSON |
| 异步生成 / 编辑 | POST /v1/images/generations/asyncPOST /v1/images/edits/async | 与对应同步请求一致,保持 stream: false |
| 查询异步任务 | GET /v1/images/tasks/{task_id} | 使用提交时的同一枚 API Key |
鉴权仍使用 Authorization: Bearer <HAPI_API_KEY>。主域名和独立图片域名的图片 API 均必须使用 /v1/images/*。
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。model 和 quality 即可;任务状态、对象存储要求、期限和错误处理保持一致。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" }'
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
适用于本站使用 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 降低保真度;其他模型以对应渠道为准。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 下载环节,不能套到本站所有上传路径;实际入口和文件上传限制以请求返回为准。
仅 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 2.6
使用 gpt-image-2.6-flare(快速迭代)或 gpt-image-2.6-sunburst(精细构图)生成完整 GIF 动画。请选择已配置这两个模型、使用 API Key 接入且支持 GIF 的图片渠道;是否可用以本站分组授权和上游权限为准。
在生图工作台或画布选择 Image 2.6 后,将输出格式设为“GIF 动图”,设置帧数、每帧时长与尺寸。提示词写清主体、动作、镜头和循环要求;上传静态参考图可生成动图。默认仍为 PNG。
https://image.hapiopen.cc/v1文生动图使用 POST /v1/images/generations;参考图使用 POST /v1/images/edits。主域名也支持图片请求。鉴权使用本站 HAPI_API_KEY,公开 Image API 的支持不代表 Codex OAuth 账号已开放同样能力。
| 参数 | GIF 用法 |
|---|---|
output_format | gif |
frame_count | 2–16 的整数,默认 9 |
frame_duration_ms | 20–2000 的整数,默认 200;取整到 10 毫秒 |
size | auto 或正整数宽高,边长为 16 的倍数,例如 512x512;表示每帧尺寸 |
n | 完整动画数量;每个结果包含所有帧,示例为 1 |
quality | auto、low、medium、high、xhigh、max |
response_format | 渠道支持的 b64_json 或 url |
partial_images 或自定义 output_compression;帧参数仅用于 GIF。以下为 Bash/cURL 示例,先设置本机的 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": "一只卡通小猫挥爪后回到起始姿势,固定镜头,白色背景,平滑循环动画。",
"output_format": "gif",
"n": 1,
"size": "512x512",
"quality": "medium",
"frame_count": 9,
"frame_duration_ms": 200,
"response_format": "b64_json"
}' > result.jsoncurl --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 后缀。
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
使用 Gemini 原生 generateContent 格式。模型名写在请求地址中;文字与参考图放在 contents[].parts 中,文生图和图像编辑使用同一个接口。
https://hapiopen.cc/v1beta/models/gemini-nano-banana-2.1:generateContent使用有权访问对应 Gemini 分组的 HAPI API Key,鉴权为 Authorization: Bearer <HAPI_API_KEY>。下方以 gemini-nano-banana-2.1 为示例;请从 模型广场 复制当前分组可用的准确模型名,替换地址中的模型部分。
/v1/images/generations、/v1/images/edits 或 OpenAI 的 messages 结构。| 字段 | 取值 | 说明 |
|---|---|---|
contents[].parts[].text | 提示词 | 与参考图放在同一条用户消息中。 |
generationConfig.responseModalities | ["IMAGE"] | 请求图片输出;需要同时返回文字时可使用 ["TEXT", "IMAGE"]。 |
generationConfig.imageConfig.imageSize | 1K、2K、4K | 选择分辨率档位,费用以渠道对应档位定价为准。 |
generationConfig.imageConfig.aspectRatio | 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 | 图片宽高比;实际像素尺寸以返回图片为准。 |
response_format | b64_json、url | 顶层扩展字段;默认 Base64 图片,url 请求图片链接。 |
contents[].parts[].inlineData | mimeType + data | 参考图 MIME 类型和不带 data URL 前缀的 Base64 内容。 |
contents[].parts[].fileData | mimeType + fileUri | 参考图 HTTP/HTTPS 链接;图片需可直接读取。 |
此接口不使用 GPT Image 的 quality、size、output_format 或 n。使用 imageSize 和 aspectRatio 控制图片规格。
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"}}。
{
"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 的部件属于思考过程,不作为最终图片展示。
{
"candidates": [{"content": {"role": "model", "parts": [
{"fileData": {"mimeType": "image/png", "fileUri": "https://example.com/result.png"}}
]}, "finishReason": "STOP"}]
}{
"candidates": [{"content": {"role": "model", "parts": [
{"inlineData": {"mimeType": "image/png", "data": "<IMAGE_BASE64>"}}
]}, "finishReason": "STOP"}]
}promptFeedback.blockReason 和 finishReason。NO_IMAGE 表示没有生成图片,SAFETY 或 IMAGE_SAFETY 表示安全审核未通过。完成配置后依次检查下面几项。不要只根据 CC Switch 的“已保存”判断接口已经可用。
https://hapiopen.cc,末尾没有 /v1。请求失败时先检查状态码,再核对 Base URL、API Key、模型名称和账户分组。
https://hapiopen.cc/v1,最终形成重复路径。改为不带 /v1 的地址。settings.json 内容,再重新启动。