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
推荐独立域名
Authorization: Bearer/images/generations
Banana-2 / Prohttps://image.hapiopen.cc/v1Authorization: Bearer/chat/completions
原始 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 角色。
streamtrue 返回 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对话消息数组;多模态内容、工具消息和开发者消息是否可用取决于模型与上游。
streamtrue 返回流式增量,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

/images/generations

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

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

/images/edits

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

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

/images/generations/async

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

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

/images/edits/async

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

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

/images/tasks/{task_id}

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

  • processing 表示仍在生成,按 Retry-After 继续等待
  • completed 时读取 result.data[0].url
  • failed 时读取 errorhttp_status
IMAGE BASE URLhttps://image.hapiopen.cc
路径兼容。 独立图片域名同时支持 /images/*/v1/images/*;主域名原有图片路径继续保留。
独立域名需要 DNS 与 HTTPS 已生效。 如果暂时无法访问 image.hapiopen.cc,先使用 https://hapiopen.cc/v1/images/*

请求头

Header必填说明
AuthorizationBearer <HAPI_API_KEY>
Content-Type生成使用 application/json;本地图片编辑使用 multipart/form-data

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高例如 1024x10241536x1024;自定义值是否可用由所选上游判断
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生成、编辑上游默认风格提示字段;常见上游值包括 vividnatural,并非所有模型都支持
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
maskfilemultipart 图片编辑-可选遮罩图;需要修改的区域由遮罩和 prompt 共同决定
mask.image_urlstringJSON 图片编辑-远程遮罩图 URL;不支持 mask.file_id
参数与接口的关系。 /images/generations/async 接受与同步生成相同的 JSON 参数;/images/edits/async 接受与同步编辑相同的 multipart 或 JSON 参数。异步请求必须保持 stream: false
上游能力边界。 HAPI 能识别并转发上表字段,不代表每个渠道账号都实现全部能力。模型映射后的上游如果不支持某项参数,可能忽略该字段或返回 400;先用最小请求验证,再逐项增加质量、格式、透明背景、遮罩或流式字段。

站内 Image Studio 已验证尺寸范围

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

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

文字生成图片

cURL · Images Generations
curl https://image.hapiopen.cc/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/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/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_urlmaskurlmaskUrlmask.url 也会被 HAPI 规范化为 mask.image_url;新接入请优先使用嵌套写法。JSON 编辑的参考图必须使用 images: [{"image_url":"https://..."}];HAPI 不支持 file_idmask.file_id。如果所选模型不支持远程遮罩 URL,请改用 multipart 的 mask=@mask.png
上传文件限制。 单个 multipart 图片或遮罩文件应保持在 20 MiB 以内;请求还要同时满足入口总请求体限制。总请求体超过入口限制时会返回 413。URL 图片的大小、格式、访问权限和下载时限还受目标上游限制。

提交异步任务

cURL · Async Images
curl -i https://image.hapiopen.cc/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": "/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/images/tasks/<TASK_ID> \
  -H "Authorization: Bearer $HAPI_API_KEY"
status是否终态处理方式
processing读取响应头 Retry-After,默认约 3 秒后继续查询
completed读取 result.data[].urlimage_url 是第一张图片的快捷字段
failed读取 http_statuserror,修正参数或稍后重新提交
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[].urldata[].b64_json,调用方应同时兼容。
  • 异步开关异步任务依赖站点启用图片对象存储。若返回 async image tasks are not enabled,请先使用同步接口。
  • 异步结果异步完成后,HAPI 会把图片转存到站点对象存储并在 result.data[].url 返回链接;异步请求中的 response_format 不会让任务结果以大段 Base64 保存在 Redis。
  • 任务期限任务元数据在最近一次状态更新后保留 24 小时,单个任务最长执行 30 分钟。对象本身的保留时间和 URL 有效期由站点对象存储配置及存储桶生命周期规则决定。
  • 重复提交当前 HAPI 公开异步接口未开放客户端幂等键、Webhook、取消任务或自定义过期时间;网络重试可能创建新任务,请在客户端记录已返回的 task_id
  • 异步编辑/images/edits/async 是 HAPI 的后台任务接口;编辑任务会按所选模型和渠道的可用能力在后台执行。

Banana Image Models

Banana-2 / Pro 生图

nano-banana-2nano-banana-pro 通过 OpenAI 兼容的 Chat Completions 接口生图。它们使用“清晰度档位 + 宽高比”控制尺寸,不接受任意像素宽高;当前上游支持 1K2K4K。HAPI 不裁剪、不缩放,并把上游返回的 PNG、JPEG 或 WebP 统一保存为 PNG。

POSThttps://image.hapiopen.cc/v1/chat/completions
使用独立图片域名。 Banana-2 / Pro 与 Images API 共用 image.hapiopen.cc,但请求路径是 /v1/chat/completions。主域名原路径仍兼容,新的接入统一使用独立图片域名。

可用模型名称

系列可用模型 ID说明
Banana-2nano-banana-2请求时必须使用完整模型 ID,不要省略 nano- 前缀。
Banana Pronano-banana-pro可用性与价格以当前分组和模型广场为准。

请求参数

参数类型必填可选值说明
modelstringnano-banana-2 / nano-banana-pro必须是当前 API Key 所属分组可用的准确模型名称。
messagesarrayOpenAI Chat 消息数组文字提示词可使用字符串;参考图使用多模态 content 数组。
streambooleanfalse图片生成使用非流式响应;省略时按 false 处理。
extra_body.google.image_config.image_sizestring1K / 2K / 4K清晰度与输出规模档位,不代表固定的最长边像素。
extra_body.google.image_config.aspect_ratiostring1:12:33:23:44:34:55:49:1616:921:9选择画布方向和比例,不能替换为自定义宽高。
参数分层。 modelmessagesstream 属于 Chat Completions 请求;真正的生图控制项位于 extra_body.google.image_config。HAPI 当前确认并转发的 Banana 生图控制项只有 image_sizeaspect_ratio

与 GPT Images 的能力对照

能力Banana-2 / Progpt-image-2
提示词messagesprompt
尺寸image_size 档位 + aspect_ratiosize 或自定义像素
独立质量参数没有;1K / 2K / 4K 只控制输出规模quality
参考图messages[].content[].image_urlmultipart 文件或 images[].image_url
每次输出数量当前契约一次请求一张,没有 n使用 n
输出格式与压缩没有已确认的独立控制字段output_format / output_compression
透明背景没有已确认的独立控制字段background
遮罩编辑没有标准 mask;通过提示词和参考图表达修改要求mask / mask.image_url
参考图保真度没有已确认的 input_fidelityinput_fidelity
公开异步任务此 Chat 端点没有任务 ID;公开 Chat 接口仍是同步 HTTP可使用 HAPI Images 异步任务接口
不要推测隐藏参数。 某个映射上游接受 temperatureseed 或其他 Chat 字段,不代表它会影响图片,也不代表所有 Banana 渠道都支持。未列入确认参数的字段可能被忽略或返回 400。
cURL · 文生图
curl https://image.hapiopen.cc/v1/chat/completions \
  -H "Authorization: Bearer <HAPI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "messages": [{
      "role": "user",
      "content": "生成一张雨后城市夜景,电影感灯光,画面中不要出现文字"
    }],
    "stream": false,
    "extra_body": {
      "google": {
        "image_config": {
          "image_size": "4K",
          "aspect_ratio": "16:9"
        }
      }
    }
  }'

使用参考图

把本地图片转换为完整 Data URL,再作为 image_url.url 放入消息内容。Data URL 必须包含真实 MIME 类型、;base64, 前缀和完整 Base64 数据;不要只传裸 Base64 字符串。

JSON · 参考图生图
{
  "model": "nano-banana-2",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "保留主体姿势,把背景改成雪山日出"},
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,<BASE64_DATA>"}
      }
    ]
  }],
  "stream": false,
  "extra_body": {
    "google": {
      "image_config": {
        "image_size": "2K",
        "aspect_ratio": "3:2"
      }
    }
  }
}
多张参考图。 可在同一个 content 数组中继续添加 image_url 项;最终可用数量、格式和内容限制仍由所选上游模型决定。
参考图容量。 Data URL 会让二进制图片增大约三分之一。请求还要经过 HAPI 网关并受上游更小限制约束,因此不要按 Nginx 的 256 MB 入口值估算可上传图片量;遇到 413 时应压缩图片或减少参考图数量。

同步响应中的图片位置

Banana 使用 Chat Completions 返回图片。不同兼容上游可能采用不同结构,客户端至少应兼容下面几种常见位置;HAPI 的站内 Image Studio 已按此规则提取首张有效图片。

响应位置内容形式处理方式
choices[].message.images[]image_url.urlurl读取 HTTPS URL 或完整 Data URL。
choices[].message.content 内容块image_url.urlurl遍历内容块并寻找图片地址。
choices[].message.content 文本Data URL、Markdown 图片链接或单独的 HTTPS URL提取完整链接;Markdown 图片链接形如 ![image](https://...)
HTTP 200 · Banana Chat Response
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "images": [{
        "image_url": {
          "url": "https://example.com/generated.png"
        }
      }]
    },
    "finish_reason": "stop"
  }]
}
不要只读取纯文字。 如果只把 choices[0].message.content 当普通文本显示,可能看不到结构化 message.images 中的图片。远程 URL 也可能带有效期,应及时下载保存。

image_size 与比例对应的预计分辨率

下表是当前上游的预计输出规格,方便选择档位和构图比例。档位不是任意像素输入,实际尺寸始终以上游返回的图片文件为准。

宽高比1K2K4K
1:11024×10242048×20484096×4096
2:3848×12641696×25283392×5056
3:21264×8482528×16965056×3392
3:4896×12001792×24003584×4800
4:31200×8962400×17924800×3584
4:5928×11521856×23043712×4608
5:41152×9282304×18564608×3712
9:16768×13761536×27523072×5504
16:91376×7682752×15365504×3072
21:91584×6723168×13446336×2688
不支持自定义像素。 可以向当前 Banana-2 / Pro 上游指定 4K,但不能指定 3840×2160 这类任意宽高。需要严格固定像素时,请在客户端下载完成后自行缩放、裁剪或补边;HAPI 只做必要的 PNG 格式归一化,不改变图片宽高。
不要混用 GPT Images 参数。 sizequalitynoutput_formatresponse_formatinput_fidelitymask 属于 GPT Images 请求体系,不能代替 Banana 的 image_sizeaspect_ratio。当前 Banana 契约不承诺识别 GPT Images 字段。

Banana 常见状态码

状态码常见原因处理建议
400模型 ID、消息结构、Data URL、档位、比例或未知参数无效保留最小请求,只使用本文确认字段;检查 nano- 前缀。
401API Key 缺失、无效或已禁用检查 Authorization: Bearer
403分组没有该模型、账户没有图片权限,或提示词/参考图触发安全策略检查模型广场和分组权限,必要时调整内容。
404误用其他路径,或当前模型映射不存在确认使用 /v1/chat/completions 和准确模型 ID。
413请求体过大,常见于多张高分辨率图片转 Data URL压缩图片、降低数量,避免重复编码。
429并发、速率、模型限额或上游容量达到限制采用退避重试,不要瞬间重复提交。
502 / 504上游响应无法解析、返回的图片地址失效,或生成时间超过链路超时检查用量记录中的上游错误;降低并发并稍后重试。
  • 实际尺寸相同档位和比例在上游升级后可能变化。请读取最终图片文件的宽高,不要把表中数值作为永久固定协议。
  • 图片处理HAPI 不裁剪、不缩放;上游返回 JPEG 或 WebP 时会转换为 PNG 保存,图片宽高保持不变。
  • 模型与价格请求前从模型广场确认当前分组提供的准确模型 ID 和价格;模型存在于文档不代表所有 API Key 都有权限调用。

Seedance Video API

Seedance 2.5 视频生成

seedance2.5 使用异步视频任务接口,支持文本、图片、视频和音频参考。提交成功会立即返回本站任务 ID;客户端随后查询状态,完成后从本站对象存储下载视频。

功能开关。 视频 API 和视频工作台默认关闭。管理员完成渠道、按秒价格和对象存储配置后,还要设置 gateway.seedance_video_enabled: true 并重启主服务。关闭时新请求返回 VIDEO_FEATURE_DISABLED,已有任务仍可由后台完成结算和清理。

端点与鉴权

方法路径用途
POSThttps://hapiopen.cc/v1/videos创建任务;使用 application/json,成功时立即返回本地不可猜测 ID。
GEThttps://hapiopen.cc/v1/videos/{id}查询当前状态、进度、错误和完成后的用量。
GEThttps://hapiopen.cc/v1/videos/{id}/content完成时返回 302 到短期签名下载地址;未完成时返回 409
GEThttps://hapiopen.cc/v1/videos列出当前 API Key 最近的视频任务,最多返回 50 条。
GEThttps://hapiopen.cc/v1/videos/quote?model=seedance2.5&seconds=15按当前渠道价格和用户倍率返回提交前报价。
POSThttps://hapiopen.cc/v1/videos/media站内工作台使用的参考媒体上传接口;表单字段为 typefile

所有端点都使用 HAPI API Key:Authorization: Bearer <HAPI_API_KEY>。任务只对创建它的用户和同一 API Key 可见;响应不会暴露上游任务 ID、渠道地址或上游 Bearer Key。创建请求可带 Idempotency-Key,同一 Key 和相同请求可安全重试;同一 Key 改变请求体会返回 409 VIDEO_IDEMPOTENCY_CONFLICT

创建参数

字段类型默认值 / 范围说明
modelstring必填:seedance2.5当前首发模型;管理员可把它映射到上游实际模型名。
promptstring顶层模式必填文本提示词;使用 content[] 模式时不要再传此字段。
secondsstring"4""4""30"字符串秒数,与 duration 互斥。
durationinteger430整数秒数,与 seconds 互斥;两者都省略时为 4 秒。
sizestring可选,如 1280x720WIDTHxHEIGHT 格式;显式 ratio 按上游规则优先。
ratiostring可选auto21:916:94:31:13:49:16;省略时由上游结合 size 处理。
resolutionstring480p支持 480p720p;兼容接收 1080p,但上游封顶 720p,因此实际按 720p 提交。
generate_audiobooleantrue是否要求生成音频。
seedinteger-1-1 表示随机;固定整数可用于可复现尝试,但结果仍受上游实现影响。
input_referencestring 或 string[]可选兼容上游的通用媒体引用;图片、视频和音频可使用 HTTP(S) URL 或 data: Base64。
imagesstring 或 string[]最多 30 张图片引用,与图片形式的 input_reference 等价。
videosstring 或 string[]最多 10 个顶层视频参考字段。
audiosstring 或 string[]最多 10 个顶层音频参考字段。
contentarray可选多模态内容模式;与顶层 promptinput_referenceimagesvideosaudios 互斥。
两种输入模式只能选一种。 顶层模式使用 prompt 加媒体字段;多模态模式把文字和媒体全部放进 content[]。混用会返回 400 INVALID_VIDEO_REQUEST
cURL · 文生视频
curl -X POST https://hapiopen.cc/v1/videos \
  -H "Authorization: Bearer <HAPI_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-video-20260813-001" \
  -d '{
    "model": "seedance2.5",
    "prompt": "a red hot air balloon over green mountains at sunrise",
    "seconds": "15",
    "size": "1280x720",
    "resolution": "720p",
    "generate_audio": true,
    "seed": -1
  }'

参考媒体与 content[]

远程引用支持公网 HTTP(S) URL 和包含 MIME 类型的完整 data: Base64 URL。content[].type 支持 textimage_urlvideo_urlaudio_url;各媒体字段的值采用 {"url":"..."} 结构。

JSON · 多模态视频生成
{
  "model": "seedance2.5",
  "duration": 15,
  "ratio": "16:9",
  "resolution": "720p",
  "content": [
    {"type": "text", "text": "gentle camera push-in, soft light"},
    {"type": "image_url", "image_url": {"url": "https://example.com/reference.jpg"}},
    {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_DATA>"}},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/reference.mp3"}}
  ]
}

HAPI 按公开的 POST /v1/videos JSON 契约转发图片、视频和音频引用。媒体上传、任务提交和结果转存由 HAPI 在服务端完成,调用方无需也不能直接访问内部处理接口;本站不会要求客户端伪造媒体 ID 或内部负载。

上传限制与远程 URL

媒体数量上限单文件上限站内上传 type
图片30 张10 MiBimage
视频10 个200 MiBvideo
音频10 个50 MiBaudio

单任务全部参考媒体合计不得超过 500 MiB。工作台先以 multipart/form-data 上传到 POST /v1/videos/media,再把响应中的短期签名 url 放入创建请求;必须使用同一用户的同一 API Key。站内上传会校验扩展名、声明 MIME、文件头、所有权、有效期和大小,并采用流式存储,避免把大视频一次性读入内存。

远程媒体必须可被服务端访问。 本站只接受 httphttpsdata:,并在提交前做 DNS 解析及私网、回环、链路本地地址预检;远程文件的实际下载、重定向、内容类型和大小规则由所选模型和渠道决定。若返回 download returned HTTP 403,请改用可直连地址、站内上传或 Base64。Base64 会增加约三分之一体积,且 POST /v1/videos 默认 JSON 请求体上限为 768 MiB;反向代理的请求体上限必须至少同步到该值。较大媒体仍应使用 POST /v1/videos/media,不要直接内联 Base64。

任务状态、进度与下载

statusprogress处理方式
queued0100已入队,尚未开始;继续轮询。
in_progress0100生成或转存中;继续轮询,不要重复创建。
completed通常为 100读取 video_urlcompleted_atusage,或访问内容端点。
failed最终值读取 error.codeerror.message,修正后用新的幂等键重新提交。
HTTP 200 · Completed Video
{
  "id": "video_sd_...",
  "object": "video",
  "model": "seedance2.5",
  "status": "completed",
  "progress": 100,
  "seconds": "15",
  "video_url": "https://storage.example/signed-video.mp4",
  "created_at": 1785248785,
  "completed_at": 1785249046,
  "usage": {"seconds": 15, "video_count": 1}
}
轮询建议。 客户端每 10 到 15 秒查询一次,整体等待时间至少 20 分钟;本站 worker 默认约每 12 秒轮询,单任务 deadline 为 1800 秒。短暂网络错误会自动重试,不会立即把任务标记为失败。视频已在上游完成但尚未成功转存时仍保持处理中。

错误与重试

状态 / 错误含义处理建议
400 INVALID_VIDEO_REQUEST字段类型、范围、输入模式或媒体限制不合法。检查 4 到 30 秒限制、seconds/duration 互斥和媒体结构。
401HAPI API Key 缺失、无效或禁用。检查 Authorization 请求头,不要把上游 Key 发给客户端。
402 VIDEO_INSUFFICIENT_BALANCE余额不足以冻结预计费用。充值、缩短时长,或联系管理员检查渠道价格。
403分组无权限或本地安全审核拒绝。检查分组可见性和内容;审核请求不要盲目重试。
404任务不属于当前 API Key,或视频功能未启用。确认任务 ID、API Key 和功能开关。
409 VIDEO_NOT_READY在任务完成前访问了 /content先查询任务,等待 completed
413入口请求体或上传文件过大。减少媒体数量、压缩文件或改用可直连 URL。
generation_failed上游生成失败;消息可能为 content moderated (nsfw)本站保留上游原始 message;调整提示词/参考媒体后重新提交。
download returned HTTP 403上游或本站无法下载远程参考媒体。改用允许服务端访问的 URL、站内上传或 Base64。
poll network error轮询链路暂时抖动。继续查询;本站以 1800 秒 deadline 为准。
503 VIDEO_PERSISTENCE_UNCERTAIN上游提交结果或本地持久化暂时无法确认。保留原 Idempotency-Key,稍后查询或重试,不要换 Key 重复扣款。
503 VIDEO_NO_ACCOUNT当前分组没有可承接 seedance2.5 的启用渠道账号。检查渠道状态、分组关联、模型映射、并发和上游 Base URL。

管理员:渠道、定价与结算

  1. 创建 OpenAI API Key 类型渠道账号

    Base URL 配置为所选兼容渠道的 /v1 根地址;Bearer Key 只保存在服务端账号密钥中,不会返回给客户端。账号必须启用并关联允许访问的分组。

  2. 配置模型映射和调度

    将站内 seedance2.5 映射到渠道实际支持的模型名称。多个可用账号可继续使用现有优先级、并发和故障转移规则。

  3. 在渠道模型定价中按秒定价

    模型填写 seedance2.5,计费模式选择 video,在 video_price_per_second 中填写自定义基础价(系统默认货币/秒)。文生、图生、视频参考和音频参考统一按秒,不按 480p、720p 或 1080p 拆价。

  4. 确认倍率与报价

    分组只负责权限、渠道可见性和现有统一倍率;它没有独立的 Seedance 视频价格。有效秒价 = 渠道每秒价 × 分组倍率(存在用户专属倍率时以其为准),GET /v1/videos/quote 和视频工作台会显示预计费用。

  5. 配置 S3/R2 并开启功能

    参考媒体和结果都依赖现有对象存储。完成配置后开启 gateway.seedance_video_enabled;还可按部署入口设置 gateway.seedance_video_max_body_size,但它不能放宽单文件和 500 MiB 业务限制。

冻结与异步结算。 创建时按“请求秒数 × 有效每秒价”在同一事务中检查余额并冻结。完成且视频转存成功后优先按 usage.seconds 结算,缺失时按请求时长,实扣不超过冻结额并释放差额;失败、超时或转存重试耗尽会释放全部冻结额。重复 capture/release 使用幂等请求 ID,不会重复结算。

存储、安全与当前发布状态

  • 30 天保留参考上传和生成视频默认保留 30 天,到期清理对象但保留任务、计费和错误元数据。video_url 和内容端点使用短期签名地址,不公开永久桶地址。
  • 密钥与日志上游 Bearer Key 不进入浏览器、API 响应或公开日志;Authorization、带敏感查询参数的 URL 和 Base64 内容应保持脱敏。
  • 传输安全渠道 Base URL 应优先使用 HTTPS,避免 Bearer Key 和媒体元数据在服务端到渠道的链路上明文传输。更换渠道地址不会改变公开 API。
  • 本地审核边界本站会审核提示词并按现有审核引擎容量抽样图片;视频和音频大文件不进入本地审核队列,上游仍可能返回内容审核失败。
  • 上线前验证启用前应使用测试渠道、测试 Key 和低价短视频验证提交、轮询、转存、扣费与退款。

验证接入

完成配置后依次检查下面几项。不要只根据 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上游模型暂时不可用。稍后重试,或切换到当前分组内的其他可用模型。
已复制到剪贴板