API v3
DEVELOPER PLATFORM

把你的算力,接入任何应用。

一套 API,调用图片、语音、音乐与视频生成;并提供 OpenAI 兼容端点供标准 SDK 直接接入。网页工作台和代码共享同一个任务队列。

下载 OpenAPI 3.1

01 / 从第一次生成开始

Base URL:https://gumy.jiangyinliang.com。登录工作台后点击顶部「API Key」取得密钥,在客户端环境变量中配置;浏览器端应用请通过你自己的后端调用,避免公开密钥。

Python · 提交 → 轮询 → 下载
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 密钥/子密钥,能力白名单对子密钥生效)。

Python · openai SDK
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 / 422JSON、类型、范围或格式错误修改请求后再提交
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 单机实际算力一致。