出图 · POST /api/generate

最常用的那个接口。异步：秒回任务号，出完通过回调或轮询拿结果。

填入你的 API Key本站所有示例里的 $MUSEAV_API_KEY 会就地换成它

只存在你自己浏览器的 localStorage 里，不会发给任何人——本站是纯静态页面，没有后端可发。共用电脑上看完记得点「清除」。

最简单的用法

用技能出图 —— 你只写一句业务描述，提示词由中台展开：

bash

curl -X POST https://manager.museav.top/api/generate \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "skill_slug": "ecom-white-backdrop",
    "input": "米白色针织衫",
    "reference_images": ["https://.../模特图.jpg"]
  }'

技能是中台维护的成套出图方法（风格、构图、光线都调好了），提示词正文不下发 —— 中台后续改了提示词，不影响你的调用代码。

技能清单见 GET /api/skills，里面标了每个技能的比例和是否需要参考图。

自己写提示词

不想用技能，自己给完整提示词：

bash

curl -X POST https://manager.museav.top/api/generate \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "英文提示词（你自己的模板）",
    "provider": "auto",
    "ratio": "3:4",
    "quality": "high",
    "background": "transparent",
    "reference_images": ["https://.../ref-1.jpg", "https://.../ref-2.jpg"],
    "callback_url": "https://你的域名/api/studio-callback?secret=xxx"
  }'

json

{ "ok": true, "jobId": "<uuid>", "status": "pending" }

参数

参数	说明
`prompt`	完整提示词。与 `skill_slug` / `template_id` 三选一
`skill_slug` + `input`	用技能：技能名 + 一句业务描述
`template_id` + `input`	用模板：模板 ID + 字段对象，服务端做确定性替换
`provider`	`auto` = 按中台路由表选上游。一般不用传
`ratio`	画幅，如 `3:4` / `9:16` / `1:1` / `4:3` / `16:9`
`quality`	`low` / `medium` / `high`，仅 gpt-image 系列上游支持，不传默认 `high`（2026-08-27 起，此前用上游默认）。带参考图时同样支持
`background`	`transparent` / `opaque`，见下
`reference_images`	参考图 URL 数组（图生图）
`image_url` + `mask`	局部重绘，成对传，见下
`callback_url`	出完图往这里 POST 结果

`background` —— 要不要透明底

transparent = 抠掉背景，出带 alpha 通道的 PNG。做贴纸、电商主图叠底、合成素材用。

关于透明背景的四件事

服务端强制 PNG 输出。 JPEG 和有损 WebP 没有 alpha 通道，透明落到这些格式上会被填成黑或白，等于白做。这个约束在中台强制，你不用也无法指定输出格式。
只有部分上游支持。 只派给路由表标了支持透明背景的上游；一家都没有时返回 400 并说明原因，不会静默给你一张白底图。
能和参考图 / 蒙版叠加。 「拿这张垫图出成透明底」是可以的，选路会同时满足两项能力。
在提示词里写 "transparent background" 没用。 那是给模型的构图描述，不是抠图开关。

opaque = 明确要不透明背景。这就是当前上游的默认行为，写出来是为了让「我确实要白底」这个意图留在任务记录里。

参考图的回落规则

模板的 generation_configs[].default_reference_images 非空时，你不传 reference_images 会自动回落到它 —— 图片转模板逆向建出的模板把原图焊在这个字段上，这是「换了文字还能出同款」的物理保证。

你传了就以你传的为准。调用方显式给的永远优先。

局部重绘（蒙版）

当前不可用，调用一律返回 400

2026-08-28 把在用的四家上游逐家实测了一遍（传原图 + 只开右下角的蒙版，要求在蒙版区画个图形）， 没有一家真正支持：它们全部返回 200 并出图，但要么整张重画，要么把图形画在画面正中—— 蒙版位置被完全无视。/v1/images/edits 端点存在不等于有局部重绘语义。

所以带 mask 的请求会稳定返回 400「当前无可用上游」。这是有意为之：静默降级成普通出图看起来完全正常，你只会以为参数写错了而反复重试反复花钱。

下面的参数契约保留，接进支持蒙版的上游后即刻生效，届时不需要改调用方代码。

只改图里标记的那一块：

bash

curl -X POST https://manager.museav.top/api/generate \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "把标记区域改成干净的白色包装",
    "image_url": "https://.../原图.jpg",
    "mask": "https://.../黑白蒙版.png",
    "callback_url": "https://..."
  }'

蒙版里白色 = 要重绘的区域，黑色 = 保留。

image_url 和 mask 必须同时提供，缺一返回 400
两张图都走 /api/upload-ref 上传拿公网直链
只派给支持蒙版的上游；当前一家都没有，所以这条路现在恒定 400「当前无可用上游」—— 前端该展示「局部重绘暂不可用」，而不是当成普通出图去重试

和 reference_images 的区别

reference_images 是「照着整体改」，mask 是「只改标记的那块」。

拿结果

回调（推荐）

出图完成或失败时，中台往你的 callback_url POST：

json

{
  "job_id": "…",
  "status": "done",
  "cdn_url": "https://…",
  "error": null,
  "elapsed_ms": 18432,
  "cost_usd": 0.042
}

status 只有 done 和 failed 两种。失败时 error 里写原因。

轮询（兜底）

回调可能丢（你那边网络抖动、服务重启）。所以再配一条：

bash

curl "https://manager.museav.top/api/jobs" -H "X-API-Key: $MUSEAV_API_KEY"

详见 GET /api/jobs。

限流

出图 120 次/小时，超了返回 429。

批量

一次要出多张（电商套图、海报批量）：用 POST /api/generate-batch，一次提交最多 32 项，参数与这里完全同构，不用自己写循环处理退避。

出图 · POST /api/generate ​

最简单的用法 ​

自己写提示词 ​

参数 ​

background —— 要不要透明底 ​

参考图的回落规则 ​

局部重绘（蒙版） ​

拿结果 ​

回调（推荐） ​

轮询（兜底） ​

限流 ​

批量 ​

相关 ​

出图 · POST /api/generate

最简单的用法

自己写提示词

参数

`background` —— 要不要透明底

参考图的回落规则

局部重绘（蒙版）

拿结果

回调（推荐）

轮询（兜底）

限流

批量

相关