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,
  "cost": 1.5,
  "image_count": 1,
  "balance": 996.5,
  "session_id": "g_b7c1e9f43a6d0528"
}

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_a1b2c3d4e5f60718"
}

{
  "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 -X POST https://your-domain.example/v1/videos/generations \
  -H "Authorization: Bearer mk-你的密钥" -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3","prompt":"图1保持人物外观，视频1参考动作，音频1参考节奏","duration_seconds":8,"resolution":"768p","aspect_ratio":"16:9","reference_images":["https://example.com/person.png"],"reference_videos":["https://example.com/motion.mp4"],"reference_audios":["https://example.com/rhythm.mp3"],"generate_audio":true}'

curl -X POST https://your-domain.example/v1/videos/generations \
  -H "Authorization: Bearer mk-你的密钥" \
  -F 'prompt=从首帧的站立动作平滑转到尾帧的回头动作' -F 'duration_seconds=5' \
  -F 'resolution=768p' -F 'aspect_ratio=9:16' -F 'input_mode=frames' \
  -F 'first_frame=@start.png' -F 'last_frame=@end.png' -F 'generate_audio=false'

async function submitAudioReferenceVideo(imageFile, audioFile) {
  async function upload(file, role) {
    const body = new FormData();
    body.append("role", role);
    body.append("file", file);
    const response = await fetch("/api/video/reference-assets", {
      method: "POST", credentials: "same-origin", body
    });
    const data = await response.json();
    if (!response.ok) throw new Error(data.error || "素材上传失败");
    return data.asset.id;
  }
  const imageId = await upload(imageFile, "images");
  const audioId = await upload(audioFile, "audios");
  const body = new FormData();
  body.append("prompt", "参考图中的人物随参考音频节奏运动");
  body.append("duration_seconds", "5");
  body.append("resolution", "768p");
  body.append("aspect_ratio", "16:9");
  body.append("input_mode", "references");
  body.append("asset_ids", JSON.stringify([imageId, audioId]));
  body.append("enable_audio_reference", "true");
  body.append("enable_video_reference", "false");
  body.append("generate_audio", "true");
  const response = await fetch("/api/video/reference-generate", {
    method: "POST", credentials: "same-origin", body
  });
  const data = await response.json();
  if (!response.ok) throw new Error(data.error || "视频任务提交失败");
  return data; // 后续查询 /api/video/tasks/ + data.task_id
}

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

{"ok":false,"id":"task_xxx","task_id":"task_xxx","kind":"video","status":"failed","model":"minimax-h3","cost":0,"reserved_cost":8,"error":{"code":"generation_failed","message":"视频生成失败，已退还额度"}}

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 -X POST https://your-domain.example/v1/chat/completions \
  -H "Authorization: Bearer mk-你的密钥" \
  -H "Content-Type: application/json" \
  --max-time 330 \
  -d '{"model":"nano-banana-2","messages":[{"role":"user","content":[{"type":"text","text":"保持构图，将背景变为黄昏海滩"},{"type":"image_url","image_url":{"url":"https://example.com/reference.jpg"}}]}],"n":1,"response_format":"url","stream":false}'

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "nano-banana-2",
  "choices": [{"index":0,"message":{"role":"assistant","content":"![generated image](https://your-domain.example/img/xxx)"},"finish_reason":"stop"}],
  "data": [{"url":"https://your-domain.example/img/xxx"}],
  "usage": {"prompt_tokens":0,"completion_tokens":1,"total_tokens":1}
}

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, "scope_label": "不限用途" }
}

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-2-flash-lite", "label": "Nano Banana 2 Flash Lite", "type": "image", "resolutions": ["1k"], "native_resolution": "1k" },
    { "id": "nano-banana-2.1", "label": "Nano Banana 2.1", "type": "image", "resolutions": ["2k"], "native_resolution": "2k" },
    { "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"
}

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

{"id":"nano-banana-2","object":"model","created":0,"owned_by":"huajing"}

{
  "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 }, "minimum_fen": 6, "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,
    "resolutions": ["1k", "2k"],
    "ratios": ["1:1", "16:9", "9:16", "4:3", "3:4"],
    "custom_ratio": true,
    "custom_size": true,
    "size_fields": ["size", "output_size", "dimensions"],
    "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 }
  ]
}