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": "2k",
    "model": "gpt-image-2.5"
  }'

{
  "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-2.5",
  "reference_count": 1,
  "cost": 2.5,
  "image_count": 1,
  "balance": 996.5,
  "session_id": "b7c1e9f4"
}

curl -X POST https://your-domain.example/v1/images/generations-async \
  -H "Authorization: Bearer mk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "一只在草地上奔跑的柴犬", "resolution": "2k"}'

{
  "ok": true,
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued",
  "kind": "text",
  "model": "gpt-image-2.5",
  "ratio": "",
  "resolution": "2k",
  "created_at": 1730000000000,
  "started_at": null,
  "finished_at": null
}

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

{
  "ok": true,
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "succeeded",
  "kind": "text",
  "model": "gpt-image-2.5",
  "ratio": "",
  "resolution": "2k",
  "created_at": 1730000000000,
  "started_at": 1730000000500,
  "finished_at": 1730000120000,
  "images": ["/img/xxxxxxxx"],
  "cost": 1,
  "image_count": 1,
  "balance": 997,
  "session_id": "g_a1b2c3d4e5f6g7h8"
}

{
  "ok": true,
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "failed",
  "kind": "text",
  "error": {
    "code": "no_channel",
    "message": "服务暂时不可用（暂无空闲生成节点），已退还余额"
  }
}

curl -X POST "{BASE}/v1/images/generations-hd4k" \
  -H "Authorization: Bearer mk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"赛博朋克城市夜景，写实","ratio":"16:9","delivery":"both","n":1}'

{
  "ok": true,
  "mode": "hd4k",
  "images": ["https://.../4k.png"],
  "images_2k": ["https://.../2k.png"],
  "images_4k": ["https://.../4k.png"],
  "delivery": "both",
  "resolution": "hd4k",
  "model": "gpt-image-2.5",
  "cost": 2.5,
  "image_count": 1,
  "balance": 997.5,
  "session_id": "a1b2c3d4"
}

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 },
    "upscale4k": null,
    "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-2" }
}

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-2.5",   "label": "GPT Image 2.5" },
    { "id": "nano-banana-2", "label": "Nano Banana 2" },
    { "id": "nano-banana-pro", "label": "Nano Banana Pro" }
  ],
  "default_model": "gpt-image-2.5",
  "key_model": null
}

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

{
  "ok": true,
  "pricing": {
    "text": { "halfFen": 2, "fen": 1, "yuan": 0.01 },
    "edit": { "halfFen": 5, "fen": 2.5, "yuan": 0.025 },
    "upscale4k": { "halfFen": 3, "fen": 1.5, "yuan": 0.015, "label": "2K高清修复4K" },
    "maxOutputImages": 3,
    "balanceUnit": "fen",
    "promo": true
  },
  "limits": {
    "max_output_images": 3,
    "max_reference_images": 1,
    "max_concurrent_per_user": 9999,
    "max_open_async_tasks": 9999,
    "max_repair_per_token": 1,
    "max_inflight_per_token": 1,
    "resolutions": ["1k", "2k"],
    "ratios": ["1:1", "16:9", "9:16", "4:3", "3:4"],
    "upscale4k": true,
    "deliveries": ["2k", "4k", "both"]
  }
}

{ "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-2.5",
      "cost": 1,
      "cost_units": 2,
      "status": "success",
      "session_id": "a8f3d2e1",
      "duration_ms": 42318,
      "duration_sec": 42.3,
      "created_at": 1754870400000,
      "images": ["https://.../a1b2c3.png"]
    }
  ],
  "speed": {
    "count": 40,
    "avg_duration_ms": 38200,
    "avg_duration_sec": 38.2,
    "by_resolution": {
      "1k": { "label": "1K", "count": 5, "avg_duration_ms": 12100, "avg_duration_sec": 12.1 },
      "2k": { "label": "2K", "count": 30, "avg_duration_ms": 28400, "avg_duration_sec": 28.4 },
      "hd4k": { "label": "4K", "count": 5, "avg_duration_ms": 61000, "avg_duration_sec": 61.0 }
    }
  }
}

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,
    "avg_duration_ms": 38120,
    "avg_duration_sec": 38.1,
    "by_resolution": {
      "1k": { "label": "1K", "count": 8, "avg_duration_ms": 12100, "avg_duration_sec": 12.1 },
      "2k": { "label": "2K", "count": 110, "avg_duration_ms": 28400, "avg_duration_sec": 28.4 },
      "hd4k": { "label": "4K", "count": 10, "avg_duration_ms": 61000, "avg_duration_sec": 61.0 }
    }
  },
  "calls": [
    {
      "id": 9012,
      "api_key_id": 7,
      "api_key": "mk-a1b2c3d********",
      "key_label": "生产环境-banana",
      "method": "POST",
      "path": "/v1/images/generations",
      "model": "nano-banana-2",
      "status": 200,
      "ok": true,
      "error_code": null,
      "cost": 1,
      "cost_units": 2,
      "image_count": 1,
      "duration_ms": 42318,
      "duration_sec": 42.3,
      "created_at": 1754870400000
    },
    {
      "method": "POST",
      "path": "/v1/images/generations",
      "model": "gpt-image-2.5",
      "status": 403,
      "ok": false,
      "error_code": "model_not_allowed",
      "cost": 0,
      "image_count": 0,
      "duration_ms": 3,
      "duration_sec": 0,
      "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 }
  ]
}