MUSE AV

出图 · 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 + 字段对象，服务端做确定性替换
providerauto = 按中台路由表选上游。一般不用传
ratio画幅，如 3:4 / 9:16 / 1:1 / 4:3 / 16:9
qualitylow / medium / high，仅 gpt-image 系列上游支持，不传用上游默认。带参考图时同样支持
backgroundtransparent / 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 会自动回落到它 —— 图片转模板逆向建出的模板把原图焊在这个字段上， 这是「换了文字还能出同款」的物理保证。

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

局部重绘（蒙版） ​

只改图里标记的那一块：

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。

相关 ​