API 接口文档

一、快速开始

1. 登录网站，进入「我的 → API 接口」，创建一个 API Key（明文仅显示一次）。

2. 请求头携带 Authorization: Bearer <你的 Key> 调用以下接口。

3. 调用生图/放大接口扣点与网页端完全一致，失败自动退款，账单可在「消费账单」中查看。

二、认证方式

所有接口（除创建 Key 外均已包含）都必须携带请求头：

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxx

Key 无效或已吊销返回 401。请妥善保管 Key，泄露可在客户端或管理后台立即吊销。

三、计费规则

费用 = 工作流基础价 + 画风预设加价（如有），与网页端同规则：

• 普通生图：1 点 / 张
• 画风预设：按工作流预设的加价点数
• 专家模式批量：1 张=1 点，2 张=3 点，3 张=5 点，4 张=8 点；Plus 通道 ×2；画风预设（如三渲二/更细腻二次元）按预设 cost 倍率
• 超分放大：3 点 / 次

最终价格以 GET /api/v1/workflows 动态返回为准，改价无需更新文档。

余额不足返回 402；任务失败不扣费，已扣自动退回。

四、接口列表

查询账号信息、剩余点数与我的 API Key 列表。

# 响应示例
{
  "user": { "user_id": "u_xxxxx", "username": "user1", "nickname": "",
            "remain_count": 27, "created": "2026-08-01 12:00" },
  "api_keys": [ { "id": 1, "name": "脚本", "created_at": "2026-08-12 10:00",
                  "last_used_at": "2026-08-12 10:05", "active": 1 } ]
}

获取已激活工作流列表：字段定义、基础价、画风预设加价（价格以此为准）。

# 响应示例（节选）
{
  "workflows": [
    { "id": "anima", "name": "yuki 绘图", "engine": "runninghub",
      "cost": 1,
      "fields": [ { "id": "positive", "type": "textarea", "label": "描述", "default": "" },
                  { "id": "preset", "type": "preset",
                    "options": [ { "value": "p_default", "label": "默认" } ] } ],
      "style_presets": [ { "id": "sp_3d", "name": "三渲二", "cost": 3 } ],
      "expert_mode": true }
  ]
}

提交生图任务，返回 task_id，随后轮询任务接口获取结果。

参数	说明
workflow_id	工作流 id，见 /workflows 返回（如 anima、gpt-image）
fields	工作流字段对象（positive/preset/seed 等，key 见 /workflows 字段定义）
sync（查询参数）	true = 同步等待结果（最长 120 秒）；默认 false = 异步

# 异步提交
POST /api/v1/generate
{ "workflow_id": "anima",
  "fields": { "positive": "赛博朋克猫娘", "preset": "p_default", "seed": 12345 } }

# 响应
{ "task_id": "3f8c2ab1...", "status": "queued", "cost": 1, "sync": false }

# 同步提交（sync=true，直接等到出图）
POST /api/v1/generate?sync=true
{ "workflow_id": "anima", "fields": { "positive": "樱花树下的少女" } }

# 响应（done 时携带图片与 seed）
{ "task_id": "...", "status": "done", "cost": 1, "sync": true,
  "images": [ { "filename": "xxx.png", "nsfw_hit": false,
                "url": "https://your-domain.com/api/cached-image/xxx.webp" } ],
  "seed": 12345, "workflow_name": "yuki 绘图" }

角色预设与画风预设（anima 工作流）

`/api/v1/workflows` 返回的字段里，`preset` 字段的 options 即全部可见角色预设 id（如 `p_f12416a4`），`style_preset` 字段的 options 即画风预设 id（含加价 cost，如 `sp_3d` 三渲二 +3 点）。生成时直接在 fields 中传 id：

# 带角色预设 + 画风预设提交
POST /api/v1/generate
{ "workflow_id": "anima",
  "fields": { "preset": "p_f12416a4",
              "style_preset": "sp_kieed",
              "positive": "赛博朋克猫娘" } }

# 计费自动按规则加价（与网页端一致），响应中 cost 为本次实扣点数

轮询任务状态直至 done 或 error（建议 2 秒间隔）。任务完成后结果保留约 5 分钟。

status	含义
queued	排队中
running	生成中
done	完成，images 数组为结果（含 url / filename / nsfw_hit）
error	失败，message 为原因（不扣费）
not_found	任务不存在或已过期

# 响应示例
{ "task_id": "...", "status": "done", "cost": 1,
  "images": [ { "filename": "xxx.png", "nsfw_hit": false,
                "url": "https://your-domain.com/api/cached-image/xxx.webp" } ],
  "seed": 12345, "workflow_name": "yuki 绘图" }

仅支持通用超分工作流（3 点/次）。二选一传图：image_data（base64 上传）或 image_id+source（站内图片）。

参数	说明
image_data	本机图片 base64（data:image/png;base64,...），不传 image_id
image_id	站内图片文件名；source 为 cache（生图结果）或 gallery（我的图库）
prompt / negative	可选，放大增强提示词
sync（查询参数）	同 generate

# 本机图片放大
POST /api/v1/upscale?sync=true
{ "image_data": "data:image/png;base64,iVBORw0KGgo..." }

# 图库图片放大
POST /api/v1/upscale
{ "image_id": "20260812_100000_0.png", "source": "gallery" }

取消排队/生成中的任务（仅限本人），已取消不扣费。

参数	说明
name	备注名（可选，最长 30 字）

# 响应：api_key 明文仅此一次返回！
{ "id": 3, "api_key": "sk_xxxx...", "name": "脚本",
  "created_at": "2026-08-12 10:00", "message": "请立即保存 API Key，明文不会再次显示" }

吊销后立即失效（仅限本人）。

五、错误码

状态码	说明
400	参数错误（如字段类型错误、放大工作流不受支持）
401	API Key 缺失 / 无效 / 已吊销，或账号被停用
402	剩余点数不足（响应含 required 与 balance 字段）
403	提示词违规 / 账号因违规临时封禁 / 无权操作他人任务
404	任务、图片或资源不存在
429	云端生成服务繁忙，请稍后重试
500	服务端错误（引擎异常等），任务未扣费

六、Python 示例

# pip install requests
import requests

BASE = "https://your-domain.com"
API_KEY = "sk_你的Key"

H = {"Authorization": f"Bearer {API_KEY}"}

# 1. 查余额
me = requests.get(f"{BASE}/api/v1/me", headers=H).json()
print("剩余点数:", me["user"]["remain_count"])

# 2. 取工作流与价格
wfs = requests.get(f"{BASE}/api/v1/workflows", headers=H).json()["workflows"]
print([(w["id"], w["cost"]) for w in wfs])

# 3. 异步生图 + 轮询
r = requests.post(f"{BASE}/api/v1/generate", headers=H, json={
    "workflow_id": "anima",
    "fields": {"positive": "赛博朋克猫娘，霓虹灯光，高细节"}
})
task_id = r.json()["task_id"]
print("task_id:", task_id)

import time
while True:
    t = requests.get(f"{BASE}/api/v1/tasks/{task_id}", headers=H).json()
    if t["status"] in ("done", "error"):
        print(t["status"], t.get("message", ""))
        break
    time.sleep(2)
for img in t.get("images", []):
    print("图片:", img["url"])

curl 示例

# 同步生图
curl -X POST "https://your-domain.com/api/v1/generate?sync=true" \
  -H "Authorization: Bearer sk_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"anima","fields":{"positive":"樱花树下的少女"}}'

# 查询任务
curl "https://your-domain.com/api/v1/tasks/<task_id>" \
  -H "Authorization: Bearer sk_你的Key"

七、注意事项

• 图片 URL 有效期为任务结果保留期（约 5 分钟），重要图片请立即下载保存（同时也会自动存入个人图库，可在网站查看）。
• 提示词与网页端同样受内容安全过滤，违规返回 403。
• 请求频率请控制在合理范围（约 1 次/秒），过高可能触发限流。
• 请遵守《用户协议》，不得使用 API 批量生成违规内容。