/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推荐独立域名 | Authorization: Bearer | /images/generations |
| Banana-2 / Pro | https://image.hapiopen.cc/v1 | Authorization: Bearer | /chat/completions |
| 原始 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/images/* 和 /v1/images/*;主域名原有图片路径继续保留。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 |
/images/generations/async 接受与同步生成相同的 JSON 参数;/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/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/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/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/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": "/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/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。/images/edits/async 是 HAPI 的后台任务接口;编辑任务会按所选模型和渠道的可用能力在后台执行。Banana Image Models
nano-banana-2 和 nano-banana-pro 通过 OpenAI 兼容的 Chat Completions 接口生图。它们使用“清晰度档位 + 宽高比”控制尺寸,不接受任意像素宽高;当前上游支持 1K、2K 和 4K。HAPI 不裁剪、不缩放,并把上游返回的 PNG、JPEG 或 WebP 统一保存为 PNG。
https://image.hapiopen.cc/v1/chat/completionsimage.hapiopen.cc,但请求路径是 /v1/chat/completions。主域名原路径仍兼容,新的接入统一使用独立图片域名。| 系列 | 可用模型 ID | 说明 |
|---|---|---|
| Banana-2 | nano-banana-2 | 请求时必须使用完整模型 ID,不要省略 nano- 前缀。 |
| Banana Pro | nano-banana-pro | 可用性与价格以当前分组和模型广场为准。 |
| 参数 | 类型 | 必填 | 可选值 | 说明 |
|---|---|---|---|---|
model | string | 是 | nano-banana-2 / nano-banana-pro | 必须是当前 API Key 所属分组可用的准确模型名称。 |
messages | array | 是 | OpenAI Chat 消息数组 | 文字提示词可使用字符串;参考图使用多模态 content 数组。 |
stream | boolean | 否 | false | 图片生成使用非流式响应;省略时按 false 处理。 |
extra_body.google.image_config.image_size | string | 是 | 1K / 2K / 4K | 清晰度与输出规模档位,不代表固定的最长边像素。 |
extra_body.google.image_config.aspect_ratio | string | 是 | 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 | 选择画布方向和比例,不能替换为自定义宽高。 |
model、messages 和 stream 属于 Chat Completions 请求;真正的生图控制项位于 extra_body.google.image_config。HAPI 当前确认并转发的 Banana 生图控制项只有 image_size 和 aspect_ratio。| 能力 | Banana-2 / Pro | gpt-image-2 |
|---|---|---|
| 提示词 | messages | prompt |
| 尺寸 | image_size 档位 + aspect_ratio | size 或自定义像素 |
| 独立质量参数 | 没有;1K / 2K / 4K 只控制输出规模 | quality |
| 参考图 | messages[].content[].image_url | multipart 文件或 images[].image_url |
| 每次输出数量 | 当前契约一次请求一张,没有 n | 使用 n |
| 输出格式与压缩 | 没有已确认的独立控制字段 | output_format / output_compression |
| 透明背景 | 没有已确认的独立控制字段 | background |
| 遮罩编辑 | 没有标准 mask;通过提示词和参考图表达修改要求 | mask / mask.image_url |
| 参考图保真度 | 没有已确认的 input_fidelity | input_fidelity |
| 公开异步任务 | 此 Chat 端点没有任务 ID;公开 Chat 接口仍是同步 HTTP | 可使用 HAPI Images 异步任务接口 |
temperature、seed 或其他 Chat 字段,不代表它会影响图片,也不代表所有 Banana 渠道都支持。未列入确认参数的字段可能被忽略或返回 400。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 字符串。
{
"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 项;最终可用数量、格式和内容限制仍由所选上游模型决定。Banana 使用 Chat Completions 返回图片。不同兼容上游可能采用不同结构,客户端至少应兼容下面几种常见位置;HAPI 的站内 Image Studio 已按此规则提取首张有效图片。
| 响应位置 | 内容形式 | 处理方式 |
|---|---|---|
choices[].message.images[] | image_url.url 或 url | 读取 HTTPS URL 或完整 Data URL。 |
choices[].message.content 内容块 | image_url.url 或 url | 遍历内容块并寻找图片地址。 |
choices[].message.content 文本 | Data URL、Markdown 图片链接或单独的 HTTPS URL | 提取完整链接;Markdown 图片链接形如 。 |
{
"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 与比例对应的预计分辨率下表是当前上游的预计输出规格,方便选择档位和构图比例。档位不是任意像素输入,实际尺寸始终以上游返回的图片文件为准。
| 宽高比 | 1K | 2K | 4K |
|---|---|---|---|
1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
2:3 | 848×1264 | 1696×2528 | 3392×5056 |
3:2 | 1264×848 | 2528×1696 | 5056×3392 |
3:4 | 896×1200 | 1792×2400 | 3584×4800 |
4:3 | 1200×896 | 2400×1792 | 4800×3584 |
4:5 | 928×1152 | 1856×2304 | 3712×4608 |
5:4 | 1152×928 | 2304×1856 | 4608×3712 |
9:16 | 768×1376 | 1536×2752 | 3072×5504 |
16:9 | 1376×768 | 2752×1536 | 5504×3072 |
21:9 | 1584×672 | 3168×1344 | 6336×2688 |
4K,但不能指定 3840×2160 这类任意宽高。需要严格固定像素时,请在客户端下载完成后自行缩放、裁剪或补边;HAPI 只做必要的 PNG 格式归一化,不改变图片宽高。size、quality、n、output_format、response_format、input_fidelity 和 mask 属于 GPT Images 请求体系,不能代替 Banana 的 image_size 和 aspect_ratio。当前 Banana 契约不承诺识别 GPT Images 字段。| 状态码 | 常见原因 | 处理建议 |
|---|---|---|
400 | 模型 ID、消息结构、Data URL、档位、比例或未知参数无效 | 保留最小请求,只使用本文确认字段;检查 nano- 前缀。 |
401 | API Key 缺失、无效或已禁用 | 检查 Authorization: Bearer。 |
403 | 分组没有该模型、账户没有图片权限,或提示词/参考图触发安全策略 | 检查模型广场和分组权限,必要时调整内容。 |
404 | 误用其他路径,或当前模型映射不存在 | 确认使用 /v1/chat/completions 和准确模型 ID。 |
413 | 请求体过大,常见于多张高分辨率图片转 Data URL | 压缩图片、降低数量,避免重复编码。 |
429 | 并发、速率、模型限额或上游容量达到限制 | 采用退避重试,不要瞬间重复提交。 |
502 / 504 | 上游响应无法解析、返回的图片地址失效,或生成时间超过链路超时 | 检查用量记录中的上游错误;降低并发并稍后重试。 |
Seedance Video API
seedance2.5 使用异步视频任务接口,支持文本、图片、视频和音频参考。提交成功会立即返回本站任务 ID;客户端随后查询状态,完成后从本站对象存储下载视频。
gateway.seedance_video_enabled: true 并重启主服务。关闭时新请求返回 VIDEO_FEATURE_DISABLED,已有任务仍可由后台完成结算和清理。| 方法 | 路径 | 用途 |
|---|---|---|
POST | https://hapiopen.cc/v1/videos | 创建任务;使用 application/json,成功时立即返回本地不可猜测 ID。 |
GET | https://hapiopen.cc/v1/videos/{id} | 查询当前状态、进度、错误和完成后的用量。 |
GET | https://hapiopen.cc/v1/videos/{id}/content | 完成时返回 302 到短期签名下载地址;未完成时返回 409。 |
GET | https://hapiopen.cc/v1/videos | 列出当前 API Key 最近的视频任务,最多返回 50 条。 |
GET | https://hapiopen.cc/v1/videos/quote?model=seedance2.5&seconds=15 | 按当前渠道价格和用户倍率返回提交前报价。 |
POST | https://hapiopen.cc/v1/videos/media | 站内工作台使用的参考媒体上传接口;表单字段为 type 和 file。 |
所有端点都使用 HAPI API Key:Authorization: Bearer <HAPI_API_KEY>。任务只对创建它的用户和同一 API Key 可见;响应不会暴露上游任务 ID、渠道地址或上游 Bearer Key。创建请求可带 Idempotency-Key,同一 Key 和相同请求可安全重试;同一 Key 改变请求体会返回 409 VIDEO_IDEMPOTENCY_CONFLICT。
| 字段 | 类型 | 默认值 / 范围 | 说明 |
|---|---|---|---|
model | string | 必填:seedance2.5 | 当前首发模型;管理员可把它映射到上游实际模型名。 |
prompt | string | 顶层模式必填 | 文本提示词;使用 content[] 模式时不要再传此字段。 |
seconds | string | "4";"4" 到 "30" | 字符串秒数,与 duration 互斥。 |
duration | integer | 4 到 30 | 整数秒数,与 seconds 互斥;两者都省略时为 4 秒。 |
size | string | 可选,如 1280x720 | WIDTHxHEIGHT 格式;显式 ratio 按上游规则优先。 |
ratio | string | 可选 | auto、21:9、16:9、4:3、1:1、3:4、9:16;省略时由上游结合 size 处理。 |
resolution | string | 480p | 支持 480p、720p;兼容接收 1080p,但上游封顶 720p,因此实际按 720p 提交。 |
generate_audio | boolean | true | 是否要求生成音频。 |
seed | integer | -1 | -1 表示随机;固定整数可用于可复现尝试,但结果仍受上游实现影响。 |
input_reference | string 或 string[] | 可选 | 兼容上游的通用媒体引用;图片、视频和音频可使用 HTTP(S) URL 或 data: Base64。 |
images | string 或 string[] | 最多 30 张 | 图片引用,与图片形式的 input_reference 等价。 |
videos | string 或 string[] | 最多 10 个 | 顶层视频参考字段。 |
audios | string 或 string[] | 最多 10 个 | 顶层音频参考字段。 |
content | array | 可选 | 多模态内容模式;与顶层 prompt、input_reference、images、videos、audios 互斥。 |
prompt 加媒体字段;多模态模式把文字和媒体全部放进 content[]。混用会返回 400 INVALID_VIDEO_REQUEST。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 支持 text、image_url、video_url、audio_url;各媒体字段的值采用 {"url":"..."} 结构。
{
"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 或内部负载。
| 媒体 | 数量上限 | 单文件上限 | 站内上传 type |
|---|---|---|---|
| 图片 | 30 张 | 10 MiB | image |
| 视频 | 10 个 | 200 MiB | video |
| 音频 | 10 个 | 50 MiB | audio |
单任务全部参考媒体合计不得超过 500 MiB。工作台先以 multipart/form-data 上传到 POST /v1/videos/media,再把响应中的短期签名 url 放入创建请求;必须使用同一用户的同一 API Key。站内上传会校验扩展名、声明 MIME、文件头、所有权、有效期和大小,并采用流式存储,避免把大视频一次性读入内存。
http、https 和 data:,并在提交前做 DNS 解析及私网、回环、链路本地地址预检;远程文件的实际下载、重定向、内容类型和大小规则由所选模型和渠道决定。若返回 download returned HTTP 403,请改用可直连地址、站内上传或 Base64。Base64 会增加约三分之一体积,且 POST /v1/videos 默认 JSON 请求体上限为 768 MiB;反向代理的请求体上限必须至少同步到该值。较大媒体仍应使用 POST /v1/videos/media,不要直接内联 Base64。| status | progress | 处理方式 |
|---|---|---|
queued | 0 到 100 | 已入队,尚未开始;继续轮询。 |
in_progress | 0 到 100 | 生成或转存中;继续轮询,不要重复创建。 |
completed | 通常为 100 | 读取 video_url、completed_at 和 usage,或访问内容端点。 |
failed | 最终值 | 读取 error.code 和 error.message,修正后用新的幂等键重新提交。 |
{
"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}
}1800 秒。短暂网络错误会自动重试,不会立即把任务标记为失败。视频已在上游完成但尚未成功转存时仍保持处理中。| 状态 / 错误 | 含义 | 处理建议 |
|---|---|---|
400 INVALID_VIDEO_REQUEST | 字段类型、范围、输入模式或媒体限制不合法。 | 检查 4 到 30 秒限制、seconds/duration 互斥和媒体结构。 |
401 | HAPI 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。 |
Base URL 配置为所选兼容渠道的 /v1 根地址;Bearer Key 只保存在服务端账号密钥中,不会返回给客户端。账号必须启用并关联允许访问的分组。
将站内 seedance2.5 映射到渠道实际支持的模型名称。多个可用账号可继续使用现有优先级、并发和故障转移规则。
模型填写 seedance2.5,计费模式选择 video,在 video_price_per_second 中填写自定义基础价(系统默认货币/秒)。文生、图生、视频参考和音频参考统一按秒,不按 480p、720p 或 1080p 拆价。
分组只负责权限、渠道可见性和现有统一倍率;它没有独立的 Seedance 视频价格。有效秒价 = 渠道每秒价 × 分组倍率(存在用户专属倍率时以其为准),GET /v1/videos/quote 和视频工作台会显示预计费用。
参考媒体和结果都依赖现有对象存储。完成配置后开启 gateway.seedance_video_enabled;还可按部署入口设置 gateway.seedance_video_max_body_size,但它不能放宽单文件和 500 MiB 业务限制。
usage.seconds 结算,缺失时按请求时长,实扣不超过冻结额并释放差额;失败、超时或转存重试耗尽会释放全部冻结额。重复 capture/release 使用幂等请求 ID,不会重复结算。video_url 和内容端点使用短期签名地址,不公开永久桶地址。完成配置后依次检查下面几项。不要只根据 CC Switch 的“已保存”判断接口已经可用。
https://hapiopen.cc,末尾没有 /v1。请求失败时先检查状态码,再核对 Base URL、API Key、模型名称和账户分组。
https://hapiopen.cc/v1,最终形成重复路径。改为不带 /v1 的地址。settings.json 内容,再重新启动。