01 / 从第一次生成开始
Base URL:https://gumy.jiangyinliang.com。登录工作台后点击顶部「API Key」取得密钥,在客户端环境变量中配置;浏览器端应用请通过你自己的后端调用,避免公开密钥。
import os, time, json, urllib.request
BASE = "https://gumy.jiangyinliang.com"
KEY = os.environ["GUMY_API_KEY"]
def call(path, payload=None):
request = urllib.request.Request(BASE + path,
data=None if payload is None else json.dumps(payload).encode(),
headers={"Authorization": "Bearer " + KEY,
"Content-Type": "application/json"})
with urllib.request.urlopen(request) as response:
return json.load(response)
task = call("/v1/images", {"prompt": "海边日落,海浪轻轻拍打沙滩",
"negative_prompt": "文字水印", "seed": 42})
task_id = task["task_id"]
while True:
detail = call(f"/v1/tasks/{task_id}")["task"]
if detail["status"] in ("failed", "canceled", "expired"):
raise SystemExit(detail.get("error"))
if detail["status"] == "done":
break
time.sleep(4)
for file in detail["result"]["files"]:
request = urllib.request.Request(BASE + file["url"],
headers={"Authorization": "Bearer " + KEY})
with urllib.request.urlopen(request) as response, \
open(file["filename"], "wb") as out:
out.write(response.read())
curl 提交示例:
curl -X POST https://gumy.jiangyinliang.com/v1/videos/h3 \
-H "Authorization: Bearer $GUMY_API_KEY" -H "Content-Type: application/json" \
-d '{"prompt":"海边日落,海浪轻轻拍打沙滩","mode":"t2va","duration":3}'
成功提交返回 HTTP 202:{"task_id":"…","status":"queued","detail_url":"/v1/tasks/…"}。202 表示已接受,生成结果以任务终态为准。
02 / OpenAI 兼容层(v3.0)
把标准 OpenAI SDK 的 base_url 指向 gumy 即可零改造调用语音、图片与转写;认证与限流与原生 API 完全一致(Bearer 密钥/子密钥,能力白名单对子密钥生效)。
from openai import OpenAI
client = OpenAI(base_url="https://gumy.jiangyinliang.com/v1",
api_key=GUMY_API_KEY)
client.models.list() # 模型清单
client.audio.speech.create(model="index-tts-2", # 同步语音(默认 mp3)
voice="gumy_default_voice.wav",
input="你好").write_to_file("hi.mp3")
client.images.generate(model="z-image", # 同步图片(默认 url)
prompt="a red cube", size="1024x1024").data[0]
client.audio.transcriptions.create( # 同步转写
model="qwen3-asr", file=open("sample.wav", "rb"),
language="zh", response_format="verbose_json")
模型名映射:z-image 文生图、flux2-klein-edit 参考图编辑、index-tts-2 语音、ace-step 音乐(含歌曲人声)、wan-bernini 视频、minimax-h3 H3 视频、qwen3-asr 转写、qwen3-asr-align 对齐。
与 api.openai.com 的语义差异:同步端点为阻塞等待(语音 ≤120s、图片 ≤180s、转写 ≤600s),超时返回 504 并附 task_id,任务继续执行、可转原生 API 轮询;图片 url 模式返回需要认证的下载地址而非公开预签名 URL;转写上传上限 200 MiB(比 OpenAI 宽);speed/instructions/quality/style 等参数接受但忽略。完整参数矩阵与错误语义见 OpenAPI 与仓库 docs/api.md。
03 / 调用约定
- 认证:所有生成、查询、上传和下载使用
Authorization: Bearer <API_KEY>。网站使用 HttpOnly 会话 Cookie,有效期 7 天。v3 起支持子密钥治理:按用途创建、限定能力白名单、随时吊销(见POST /v1/keys)。 - 请求:生成接口使用
application/json,最大 64 KiB;参数必须使用声明的 JSON 类型,未知字段、空白提示词和非有限数值返回 4xx。 - 任务:queued → running → uploading → done;另有 failed、canceled、expired。progress 是阶段估计,不是实际采样百分比。H3 冷启动与模型切换可能需要数分钟。
- 轮询与推送:建议每 4 秒查询;也可订阅
GET /v1/tasks/{id}/events的 SSE 流(status/done/error 事件,≤15s 心跳,终态后关闭;重连即全量快照)。时间戳为 Unix 秒;列表支持 capability/status 过滤、limit/offset 分页、fields=summary 裁剪与 since 增量游标。 - 产物:done 后 result.files[] 提供带认证的相对下载 URL,保留 7 天;
GET /v1/tasks/{id}/archive一键打包 zip(含 manifest)。过期任务仍可查询元数据,下载返回 410。 - 幂等:建议每次生成携带唯一 Idempotency-Key(1–128 ASCII 字符)。相同键与规范化参数返回原任务,不同参数返回 409;数据库保留期间跨重启有效。无幂等键的 POST 超时不能盲目重试。
- 容量:一个 GPU 串行执行,最多 20 个活跃任务,满队列返回 429。变体批量(同参数多 seed 成组,group_id 贯穿列表与 manifest)与 webhook 终态回调(HMAC-SHA256 签名、1s/10s/60s 退避重试、投递记录可查)见 OpenAPI。Windows 必须开机联网;这是个人私有服务,暂无计费、多租户或可用性 SLA。
- 上传:POST /v1/uploads,multipart/form-data 的 file 字段,PNG/JPEG/WebP/音频/MP4,最多 200 MiB;将返回的 filename 传给 H3 ref2va 的 image、首尾帧 first_frame/last_frame 或语音克隆 voice_upload。上传文件可经
GET /v1/uploads列出复用、无活跃引用时可删。旧 /api/upload 为兼容别名。
GET /v1/tasks 任务列表(capability/status/group_id/limit/offset/fields/since)
GET /v1/tasks/{id} 任务详情
GET /v1/tasks/{id}/events 进度 SSE 流
GET /v1/tasks/{id}/archive 产物 zip 打包
DELETE /v1/tasks/{id} 取消任务
POST /v1/uploads 上传参考媒体(≤200 MiB)
GET /v1/uploads 列出上传文件(引用检查)
DELETE /v1/uploads/{filename} 删除未被引用的上传
GET /v1/usage 用量统计(capability/day/key 维度)
GET/POST/DELETE /v1/keys 子密钥治理
GET/POST/DELETE /v1/webhooks 终态回调注册与投递记录
GET/POST/DELETE /v1/presets 自定义制作预设
GET /v1/capabilities 能力目录与参数白名单
GET /healthz 网关存活(无需认证)
GET /healthz/agent 节点状态,需要认证
音乐使用 ACE-Step 1.5XL Turbo + Qwen 4B:默认纯音乐(10–120 秒,FLAC/48kHz/立体声,可控制风格、BPM 与调性),设置 instrumental: false 并填写歌词后生成歌曲/中文 rap(language: zh/yue/en)。语音支持预置音色与上传参考音克隆双模式(推荐 voice_upload:≤10 MiB WAV/MP3/FLAC 的真人参考音,仅限本人或已获同意的声音;预置枚举仅保留一个默认音色)。图片支持 negative_prompt 负向提示词(提供时采样 CFG 自动升至 2 生效;image_edit 编辑链不支持)。H3 支持首尾帧控制(fl2va/t2va 模式的 first_frame/last_frame,与 ref2va 互斥);ref2va 另支持参考视频 reference_video 与源音轨保留(分辨率边界与常见报错口径见 docs/api.md)。生成指令以实际试听/查看结果为准;视频尺寸按模型对齐规则取整,实际输出以媒体文件为准。
04 / 参数参考
以下内容直接来自服务发布的 OpenAPI,和服务端参数校验共用能力定义——以这里的动态区为准,本页静态描述如与之冲突则失效。
05 / 错误与恢复
参数和协议错误返回 {"error":"可读说明","code":"validation_error","request_id":"…"},响应头携带 X-Request-ID;OpenAI 兼容端点返回 OpenAI 风格 {"error":{"message","type","param","code"}}。接入排查请同时保留 request_id 与 task_id。
| 状态码 | 含义 | 处理 |
|---|---|---|
| 400 / 415 / 422 | JSON、类型、范围或格式错误 | 修改请求后再提交 |
| 401 | 认证失败 | 检查密钥或重新登录 |
| 403 | 子密钥能力白名单拒绝 / 内置资源只读 | 换用有权限的密钥 |
| 404 / 410 | 不存在 / 产物过期 | 检查 ID 或创建新任务 |
| 409 | 幂等键冲突、终态无法取消或上传被引用 | 查询原任务/引用清单 |
| 413 | 请求或上传文件太大 | 缩小请求 |
| 429 | 活跃任务达到上限 | 按 Retry-After 等待 |
| 502 / 503 / 504 | 节点或代理不可用 / 同步等待超时 | 查询节点状态或转轮询 |
传输中断时保留幂等键,避免重复占用 GPU;已经取得 task_id 时优先查询任务。网关重启后遗留的执行中任务进入 reconciling 并按持久执行回执重新入队,不会直接判失败;排队任务保留。失败任务不会自动重跑。nginx 等上游错误可能返回 HTML,客户端先判断状态码和 Content-Type。
06 / 接入验收清单
2026-10-04 v3.0 发布验收:152 项自动化网关测试通过(含 OpenAI 兼容层、任务查询/用量/密钥/webhook/预设/上传管理、SSE 与归档);agent dry-run 16 条链路全绿(含负向提示词、H3 首尾帧、多格式音频转换、上传管理端点);OpenAI SDK 四端点真实调用通过。此前 2026-09-20 首发验收与 2026-10-03/04 的 v2、歌曲、语音双模式验收记录见仓库 docs/。
已由未参与实现的独立 agent 复核 API、代码、桌面体验与产物,未发现新的发布阻断问题。这是个人服务的独立工程复核,不是外部机构认证或 SLA。部分浏览器验收经测试端本机转发完成;整机冷启动、任意网络环境和长期运行仍需持续验证。
- 无认证请求返回 401;错误类型和越界参数返回 4xx。
- 图片、语音、视频分别完成提交、轮询、下载;检查产物哈希及解码。
- 同幂等键重复提交只生成一个任务,改变正文得到 409。
- 取消排队任务后不再执行;断线重连可以继续查询原任务。
- 网页中预览、播放、下载可用;历史列表刷新不打断播放。
标准参考:OpenAPI 3.1 · 幂等请求实践 · HTTP 202。
API 版本以 /v1/capabilities 的 versions.api 为准(页头动态注入,静态回退 v3)。新增字段可能向后兼容增加;破坏性变更使用新 API 主版本。当前服务限制与 Windows 单机实际算力一致。