Chapter Zero · Getting Started

API 文档

OpenAI 兼容接口。把 base_url 改成 https://ovolove.pro/v1，把 api key 换成你在 dashboard 创建的 ovolove key 即可。

01

获取 API Key

  1. 注册账号 → /signup
  2. 登录后到 /dashboard/keys 创建 API key
  3. 给账号充值 /dashboard/topup
02

Endpoint

  • GET/v1/models— 列出可用模型
  • POST/v1/images/generations— 生成图像（OpenAI 兼容）
  • POST/v1/images/edits— 编辑图像（multipart 上传）

其他 OpenAI 端点（embeddings、chat、audio 等）当前不开放。

03

鉴权

在每个请求 header 里附带 Authorization: Bearer sk-ovo-...

04

生图示例

curl https://ovolove.pro/v1/images/generations \
  -H "Authorization: Bearer sk-ovo-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a tiny ceramic vase with a single flower",
    "size": "1024x1024",
    "n": 1
  }'
05

请求参数

字段类型默认说明
promptstring必填生成描述。
modelstringgpt-image-2模型 id。可选 gpt-image-1 / 1.5 / 2。
sizestring1024x1024尺寸，例如 1024x1024、1024x1536、1536x1024。
ninteger1一次生成几张，1-4。
response_formatstringb64_json目前固定为 b64_json，返回 base64 PNG。
06

错误码

  • 401 unauthorized — API key 无效或被吊销
  • 402 insufficient_balance — 余额不足
  • 400 prompt_blocked — prompt 触发关键词黑名单
  • 400 price_not_found — 当前 model+size 组合未开放
  • 429 rate_limited — 限流；header Retry-After 或响应里 retry_after_seconds 字段提示等待秒数
  • 502 upstream_failed — 上游失败，余额已自动退回
  • 503 no_upstream — 没有可用上游通道，请稍后重试

错误响应格式：{ detail: { code, message } }

07

计费规则

  • · 按张计费：单价 = (model, size) 决定，n 张 = 单价 × n
  • · 同一用户严格串行（行锁），自动排队
  • · 预扣余额，调用上游失败自动退款（写一条 type=refund 的流水）
  • · 限流：单用户 60 次 / 5 分钟（包含 /v1/images/generations、/v1/images/edits 及网页生图）
08

当前价格

加载中…

价目随时可能调整，建议从 GET /api/public/prices 实时拉取。

09

图像编辑（multipart）

上传一张或多张参考图，提供 prompt 和（可选的）mask。multipart/form-data。

curl https://ovolove.pro/v1/images/edits \
  -H "Authorization: Bearer sk-ovo-..." \
  -F "image=@reference.png" \
  -F "prompt=put a teacup next to it" \
  -F "size=1024x1024" \
  -F "n=1"

# 多张参考图：重复 -F image=@xxx
# 提供 mask（白色区域=替换，黑色=保留）：
#   -F "mask=@mask.png"

字段：image（必填，可重复，最多 16 张）、prompt（必填）、mask（可选）、model、size、n。计费规则同生成。

10

浏览器内调用

如果你只是在浏览器里生图、不写后端，建议直接用网页工作台 /dashboard/generate。 它通过 session cookie 鉴权，不需要管理 API key。 如果坚持在 SPA 里调，注意 不要把 API key 写在前端代码里——它会被任何用户偷走。