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": 2,
  "reference_link_mode": true,
  "cost": 1.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 https://your-domain.example/v1/videos/generations \
  -H "Authorization: Bearer mk-视频密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3","prompt":"黄昏海边，一辆复古摩托车驶过，电影镜头","duration_seconds":8,"resolution":"768p","aspect_ratio":"16:9","reference_images":["https://example.com/reference.jpg"]}'

curl -X POST https://your-domain.example/v1/videos/generations \
  -H "Authorization: Bearer mk-视频密钥" \
  -F 'prompt=黄昏海边，电影镜头' -F 'duration_seconds=8' \
  -F 'resolution=768p' -F 'aspect_ratio=16:9' -F 'reference_images=@reference.jpg'

{"ok":true,"id":"task_xxx","status":"queued","model":"minimax-h3","prompt":"黄昏海边","duration_seconds":8,"resolution":"768p","aspect_ratio":"16:9","reference_count":1,"cost":8,"reserved_cost":8,"progress":0,"stage":"queued","progress_message":"等待生成","created_at":1760000000000}

curl https://your-domain.example/v1/videos/config -H "Authorization: Bearer mk-视频密钥"

curl https://your-domain.example/v1/videos/tasks -H "Authorization: Bearer mk-视频密钥"

curl -X POST "{BASE}/v1/images/upscale" \
  -H "Authorization: Bearer mk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/in.png","resolution":"4k"}'

{
  "ok": true,
  "mode": "canvas_upscale",
  "resolution": "4k",
  "images": ["https://.../img/xxxxxxxx"],
  "cost": 2,
  "image_count": 1,
  "balance": 998
}

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

{
  "ok": true,
  "credits": 998.5,
  "pricing": {
    "text": { "halfFen": 1, "fen": 0.5, "yuan": 0.005 },
    "edit": { "halfFen": 3, "fen": 1.5, "yuan": 0.015 },
    "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", "scope": null }
}

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": "gpt-image-2.5-high", "label": "GPT Image 2.5 high" },
    { "id": "nano-banana-2", "label": "Nano Banana 2" },
    { "id": "nano-banana-pro", "label": "Nano Banana Pro", "type": "image" },
    { "id": "minimax-h3", "label": "MiniMax H3", "type": "video" }
  ],
  "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": 1, "fen": 0.5, "yuan": 0.005 },
    "edit": { "halfFen": 3, "fen": 1.5, "yuan": 0.015 },
    "upscale4k": null,
    "maxOutputImages": 3,
    "balanceUnit": "fen",
    "promo": false
  },
  "canvas_upscale": { "2k": 1, "4k": 2, "8k": 4 },
  "video_h3": {
    "model": "minimax-h3",
    "durations": [5,6,7,8,9,10,11,12,13,14,15],
    "resolutions": ["768p", "1080p"],
    "aspect_ratios": ["16:9", "9:16"],
    "pricing": { "rate_fen_per_second": { "768p": 0, "1080p": 0 }, "reference_enabled": false, "reference_fen": 0 },
    "concurrency_limit": 9999,
    "max_open_tasks": 9999
  },
  "limits": {
    "max_output_images": 3,
    "max_reference_images": 30,
    "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": false,
    "deliveries": []
  }
}

{ "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",
      "duration_ms": 42318,
      "duration_sec": 42.3,
      "created_at": 1754870400000,
      "images": ["https://.../a1b2c3.png"]
    },
    {
      "id": 43,
      "prompt": "海边日落时的帆船",
      "ratio": "16:9",
      "resolution": "768p",
      "model": "minimax-h3",
      "cost": 15,
      "cost_units": 30,
      "status": "success",
      "duration_ms": 128000,
      "duration_sec": 128.0,
      "created_at": 1754870500000,
      "images": [],
      "video_url": "https://your-domain.example/media/video/43/SIGNATURE",
      "videos": ["https://your-domain.example/media/video/43/SIGNATURE"],
      "video_duration_seconds": 10
    }
  ],
  "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,
      "reference_count": 0,
      "duration_ms": 3,
      "duration_sec": 0,
      "created_at": 1754870300000
    }
  ]
}

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