HTTP API

CLI 与 MCP 都是对这组接口的封装。需要在自己的服务里集成时，可以直接调用。

项	值
Base URL	`https://ai.suzatei.com`
鉴权	请求头 `X-Model-Key: sk-...`（注意：生图接口用这个头，不是 `Authorization: Bearer`；LLM 接口才用 Bearer，见 LLM API）
格式	JSON；错误统一为 `{"error": "说明", "code": "可选错误码"}`

接口一览

方法	路径	说明
`GET`	`/workspace/api/generate/models`	模型目录（系列 → 模式 → `model` id、参数、参考图要求）
`POST`	`/workspace/api/generate/submit`	提交生成任务
`GET`	`/workspace/api/generate/record/{id}`	查询任务状态与结果
`GET`	`/workspace/api/generate/history`	生成历史，`limit`（1–100）、`offset` 分页
`DELETE`	`/workspace/api/generate/record/{id}`	删除一条记录
`POST`	`/workspace/api/generate/upload`	上传参考素材（图像编辑类模式需要）

生成是异步的：提交 → 轮询 → 下载。

1. 获取模型目录

curl -s https://ai.suzatei.com/workspace/api/generate/models \
  -H "X-Model-Key: $PHOENIX_MODEL_KEY"

返回 series[].modes[]。目录只包含你的 Key 当前可用（已上架）的模式，不同账号 / 分组看到的可能不同。每个模式包含：

字段	说明
`model`	提交时用的模型 id
`params`	该模式支持的参数（`name`、`default`、`options`、`required`）
`refs`	需要的参考素材；为空数组表示纯文生图

params 只能使用目录里列出的字段。模型 id 和参数请以此接口为准，不要硬编码。

2. 提交任务

curl -s https://ai.suzatei.com/workspace/api/generate/submit \
  -H "X-Model-Key: $PHOENIX_MODEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image",
    "model": "<目录里的 model id>",
    "prompt": "一只浴火重生的凤凰",
    "params": {}
  }'

字段	必填	说明
`kind`	是	目前使用 `image`
`model`	是	模型目录中的 `model`
`prompt`	是	画面描述
`params`	否	模型参数，字段见目录
`refs`	否	参考素材，格式见下文「参考图」

响应：{"generation": {"id": "g_xxx", "status": "processing", ...}}。

提交时会按模型单价预扣额度；上游提交失败或任务最终失败，会自动全额退回。用 Key 调用时，扣费会关联到这把 Key 所属的用户，并记入 NewAPI 使用日志。未上架的模型会返回 403 MODEL_NOT_ENABLED。

3. 轮询结果

curl -s https://ai.suzatei.com/workspace/api/generate/record/g_xxx \
  -H "X-Model-Key: $PHOENIX_MODEL_KEY"

`status`	含义
`processing`	生成中，继续轮询
`completed`	完成，结果在 `results`
`failed`	失败，原因在 `error`

建议每 3 秒轮询一次（服务端对过密的轮询会直接返回缓存结果）
通常几十秒完成，客户端建议最多等 180 秒，超时后保留 id 稍后再查
results 里是站内相对路径，例如 /workspace/api/generate/file/g_xxx/0?k=...，需要拼上 https://ai.suzatei.com 才能下载。链接自带访问令牌，下载时无需再带 Key（CLI 与 MCP 已自动补全为完整 URL）
结果文件只保留一段时间（默认约 6 小时，以服务端配置为准），请生成后及时下载保存。过期后记录仍在，但文件已清理

参考图（图像编辑类模式）

目录中 refs 非空的模式需要先上传素材，再在提交时引用：

# 1) 上传，body 直接是文件二进制；kind 为 image / video / audio
curl -s "https://ai.suzatei.com/workspace/api/generate/upload?kind=image&name=input.png" \
  -H "X-Model-Key: $PHOENIX_MODEL_KEY" \
  --data-binary @input.png
# → {"attachment": {"id": "att_xxx", ...}}

# 2) 提交时：refs 的键是目录里 refs[].field，值是素材 id 数组
curl -s https://ai.suzatei.com/workspace/api/generate/submit \
  -H "X-Model-Key: $PHOENIX_MODEL_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"image","model":"<编辑类 model id>","prompt":"改成夜景","params":{},"refs":{"images":["att_xxx"]}}'

上传限制：单文件 image ≤ 15 MB、video ≤ 60 MB、audio ≤ 30 MB；默认每分钟 30 次、每天 50 个。文件内容必须与 kind 一致（按文件头校验）。素材只属于上传者，提交成功后会自动清理。

CLI 与 MCP 目前只支持纯文生图，编辑类模式请用本页的 HTTP 接口。

Python 完整示例

import os, time, requests

BASE = "https://ai.suzatei.com"
H = {"X-Model-Key": os.environ["PHOENIX_MODEL_KEY"]}

catalog = requests.get(f"{BASE}/workspace/api/generate/models", headers=H, timeout=30).json()
modes = [m for s in catalog["series"] for m in s["modes"]]
model = next(m for m in modes if m["group"] == "image" and not m["refs"])["model"]

r = requests.post(f"{BASE}/workspace/api/generate/submit", headers=H, timeout=60,
                  json={"kind": "image", "model": model, "prompt": "一只浴火重生的凤凰", "params": {}})
r.raise_for_status()
gid = r.json()["generation"]["id"]

deadline = time.time() + 180
while time.time() < deadline:
    g = requests.get(f"{BASE}/workspace/api/generate/record/{gid}", headers=H, timeout=30).json()["generation"]
    if g["status"] == "completed":
        for i, path in enumerate(g["results"]):
            r = requests.get(BASE + path, timeout=120)
            ext = "png" if "png" in r.headers.get("content-type", "") else "jpg"   # 输出格式随模型参数而定
            open(f"out-{i}.{ext}", "wb").write(r.content)
        break
    if g["status"] == "failed":
        raise RuntimeError(g.get("error") or "生成失败")
    time.sleep(3)
else:
    print("仍在生成，稍后用这个 id 查询：", gid)

限制

提交默认每分钟最多 20 次
当前只开放图像生成
状态码与重试建议见错误码与重试