API 文档

curl -X POST https://your-domain.example/v1/images/generations \
  -H "Authorization: Bearer mk-你的密钥" \
  -H "Content-Type: application/json" \
  --max-time 330 \
  -d '{
    "prompt": "极简主义产品摄影：一只哑光黑陶瓷咖啡杯放在浅灰水泥台面上，柔和顶光，阴影干净，高级商业质感",
    "ratio": "1:1",
    "resolution": "4k",
    "model": "gpt-image"
  }'

{
  "error": {
    "code": "prompt_rejected",
    "message": "提示词未通过内容审核（露骨色情内容）",
    "hint": "提示词可能触发了内容审核。建议去掉真人姓名、品牌标识、暴力或成人相关描述后重试。"
  },
  "balance": 1000
}

curl -X POST https://your-domain.example/v1/images/edits \
  -H "Authorization: Bearer mk-你的密钥" \
  --max-time 330 \
  -F "image=@./reference.png" \
  -F "prompt=保持人物姿势不变，把背景换成黄昏海滩，增加暖色边缘光" \
  -F "resolution=2k"

curl -X POST https://your-domain.example/v1/images/edits \
  -H "Authorization: Bearer mk-你的密钥" \
  -H "Content-Type: application/json" \
  --max-time 330 \
  -d '{
    "image_url": "https://example.com/reference.jpg",
    "prompt": "转换成水彩插画风格，保留构图",
    "ratio": "4:3"
  }'

{
  "ok": true,
  "mode": "image_to_image",
  "images": ["https://.../edited.png"],
  "finalText": "已将背景替换为黄昏海滩。",
  "resolution": "2k",
  "model": "gpt-image",
  "reference_count": 1,
  "cost": 2.5,
  "image_count": 1,
  "balance": 996.5,
  "session_id": "b7c1e9f4"
}

curl https://your-domain.example/v1/balance \
  -H "Authorization: Bearer mk-你的密钥"

{
  "ok": true,
  "credits": 998.5,
  "pricing": {
    "text": { "halfFen": 2, "fen": 1, "yuan": 0.01 },
    "edit": { "halfFen": 5, "fen": 2.5, "yuan": 0.025 },
    "maxOutputImages": 3,
    "balanceUnit": "fen",
    "promo": false
  }
}

curl https://your-domain.example/v1/me \
  -H "Authorization: Bearer mk-你的密钥"

{
  "ok": true,
  "username": "alice@example.com",
  "email": "alice@example.com",
  "credits": 998.5,
  "credit_unit": "fen",
  "created_at": 1754870400000,
  "key": { "label": "生产环境-banana", "model": "nano-banana" }
}

curl -X POST https://your-domain.example/v1/redeem \
  -H "Authorization: Bearer mk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"code": "FL53HIJDSTQF"}'

{ "ok": true, "added": 100, "balance": 1098.5 }

{
  "ok": true,
  "models": [
    { "id": "gpt-image",   "label": "GPT Image" },
    { "id": "nano-banana", "label": "Nano Banana" }
  ],
  "default_model": "gpt-image",
  "key_model": null
}

{
  "ok": true,
  "models": [ { "id": "nano-banana", "label": "Nano Banana" } ],
  "default_model": "nano-banana",
  "key_model": "nano-banana"
}

{
  "ok": true,
  "pricing": {
    "text": { "halfFen": 2, "fen": 1, "yuan": 0.01 },
    "edit": { "halfFen": 5, "fen": 2.5, "yuan": 0.025 },
    "maxOutputImages": 3,
    "balanceUnit": "fen",
    "promo": false
  },
  "limits": {
    "max_output_images": 3,
    "max_reference_images": 1,
    "max_concurrent_per_user": 3,
    "resolutions": ["1k", "2k", "4k"],
    "ratios": ["1:1", "16:9", "9:16", "4:3", "3:4"]
  }
}

{ "ok": true, "uptime": 86400.5, "inflight": 2 }

curl "https://your-domain.example/v1/generations?limit=5" \
  -H "Authorization: Bearer mk-你的密钥"

{
  "ok": true,
  "generations": [
    {
      "id": 42,
      "prompt": "一只在草地上奔跑的柴犬",
      "ratio": "16:9",
      "resolution": "2k",
      "model": "gpt-image",
      "cost": 1,
      "cost_units": 2,
      "status": "success",
      "session_id": "a8f3d2e1",
      "created_at": 1754870400000,
      "images": ["https://.../a1b2c3.png"]
    }
  ]
}

curl "https://your-domain.example/v1/usage?limit=20" \
  -H "Authorization: Bearer mk-你的密钥"

{
  "ok": true,
  "scope": "key",
  "summary": {
    "days": 7,
    "total": 128,
    "succeeded": 124,
    "failed": 4,
    "images": 131,
    "cost": 141.5,
    "cost_units": 283
  },
  "calls": [
    {
      "id": 9012,
      "api_key_id": 7,
      "api_key": "mk-a1b2c3d********",
      "key_label": "生产环境-banana",
      "method": "POST",
      "path": "/v1/images/generations",
      "model": "nano-banana",
      "status": 200,
      "ok": true,
      "error_code": null,
      "cost": 1,
      "cost_units": 2,
      "image_count": 1,
      "duration_ms": 42318,
      "created_at": 1754870400000
    },
    {
      "method": "POST",
      "path": "/v1/images/generations",
      "model": "gpt-image",
      "status": 403,
      "ok": false,
      "error_code": "model_not_allowed",
      "cost": 0,
      "image_count": 0,
      "duration_ms": 3,
      "created_at": 1754870300000
    }
  ]
}

{
  "ok": true,
  "ledger": [
    { "delta": -3,  "delta_units": -6, "reason": "文生图 预扣最多 3 张", "balance_after": 997,   "created_at": 1754870400000 },
    { "delta": 2,   "delta_units": 4,  "reason": "按实际输出张数退回差额", "balance_after": 999, "created_at": 1754870460000 },
    { "delta": 100, "delta_units": 200,"reason": "兑换码充值 FL53HIJDSTQF", "balance_after": 1099, "created_at": 1754870500000 }
  ]
}