Muse Image API 参数文档

限制条件一览

Muse Image 能做什么、不能做什么,都在这张表里。接入前请逐条核对:文生图,或带 1-4 张参考图的图生图;一次一张,约 2.5MP,没有 4K,不支持蒙版。

不支持的取值和字段在建任务前返回 400,不扣费(唯一的例外是 quality:可以传,但会被忽略);报错原文见下方「常见报错」。

不保证每次都成功

文生图与图生图

同一个模型名、同一个端点,按你有没有传参考图来区分。两种方式同价,每张 $0.02。

一张参考图放 image(或 image_url),多张放 images(或 image_urls);两种一起传时,单张字段里的图排在最前面,合计最多 4 张。每张图是公网 URL 或 base64 data URI,PNG、JPEG 或 WebP,单张最大 10 MB、合计最大 24 MB。不支持蒙版:要改哪一块,直接写进提示词。

认证

Authorization: Bearer YOUR_API_KEY

快速开始

文生图

# ─── Text-to-image, one image per request ────────────────
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image",
    "prompt": "A bakery storefront at dawn, a hand-painted sign that reads \"MORNING LOAF\", warm window light",
    "aspect_ratio": "3:2"
  }'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-image" } }


# ─── Poll for the result ──────────────────────────────────
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
# { "code": 200, "data": { "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."],
#     "images": [{ "url": "https://r2.apimodels.app/...", "width": 1920, "height": 1280 }] } }


# ─── One call, OpenAI style: an OpenAI-style size and no callback_url ──
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image",
    "prompt": "A minimalist travel poster of Kyoto in autumn, the title \"KYOTO\" in bold letters at the top",
    "size": "2048x1152"
  }'
# { "created": ...,
#   "data": [{ "b64_json": "...", "url": "https://r2.apimodels.app/...", "width": 2048, "height": 1152 }],
#   "size": "2048x1152" }

默认是异步:建任务拿 taskId,再轮询 GET /v1/images/generations?task_id=,state 为 completed 时从 data.resultUrls 取图,data.images 给出实际宽高;failed 时原因在 data.failMsg,不扣费。我们测试中每张约 35-70 秒,每 5 秒轮询一次即可。想一次调用直接拿图,就传 OpenAI 风格的 size 且不带 callback_url:请求会一直等到出图,响应直接是 { created, data: [{ b64_json, url, width, height }], size },加 "response_format": "url" 可以不要 base64。OpenAI SDK 的 images.generate 拿到的也是这种一次返回的响应。

图生图(1-4 张参考图)

同一个模型名、同一个端点,在请求里加参考图即可,价格不变。一张用 image,多张用 images;第 1 张是主图。提示词里说明哪些保留、哪些要改,传多张时说明每张的用途。建好任务后,按上面文生图的方式轮询。

# ─── Image-to-image: 1 to 4 reference images, the first is the main image ──
# Same endpoint, model id and price ($0.02 per image) as text-to-image.
# image for one picture, images for several (image_url / image_urls also work);
# public URLs or base64 data URIs, PNG / JPEG / WebP, up to 10 MB each and 24 MB in total.
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image",
    "prompt": "Use the first image as the base and keep its lighting. Put the ceramic cup from the second image on the wooden table, next to the laptop",
    "images": [
      "https://example.com/desk-scene.jpg",
      "https://example.com/ceramic-cup.png"
    ],
    "aspect_ratio": "3:2"
  }'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-image" } }
# Poll the taskId exactly as in the text-to-image example.

请求参数

以下字段不支持,传了返回 400:mask、mask_url(蒙版 / 局部重绘),resolution: "4K",background: "transparent",negative_prompt,seed。参考图超过 4 张也返回 400。

输出尺寸

每张约 2.5MP。比例由 aspect_ratio 或 size 决定,像素由模型决定:同一个比例总是交回同一个原生尺寸。没有 4K,也没有其他分辨率档位:size 只决定比例。更小的 size 交回原生尺寸;超过约 2.6MP 的 size(3840x2160、2048x2048)或 resolution "4K" 直接返回 400,不会缩小后交付。下表是我们 2026 年 10 月 30 日 7 单测试交回的尺寸。

• 交付格式默认是 JPEG(质量 95);要 PNG 就传 output_format: "png",要 WebP 就传 output_format: "webp"。没有透明背景:background: "transparent" 返回 400。
• 速度:我们测试中每张约 35-70 秒(7 单为 34-67 秒)。
• 实际宽高看结果里的 data.images;一次调用模式下看每项的 width / height 和顶层的 size。
• 结果文件保留 30 天后自动删除,请及时下载或转存。

不支持的输入

• 蒙版(局部重绘):mask、mask_url 任一非空都返回 400。要改哪一块,直接在提示词里写清楚。
• 超过 4 张参考图:返回 400。image、image_url、images、image_urls 里的图合在一起算。
• n 大于 1:返回 400。要多张就并行发多个请求,每个请求单独计费、单独可查。
• 超过约 2.6MP 的 size(3840x2160、2048x2048)和 resolution "4K":返回 400。没有 4K,出图约 2.5MP。
• 透明背景:background: "transparent" 返回 400。
• negative_prompt 和 seed:都返回 400。没有反向提示词,想要什么就正面写进 prompt;没有 seed,同一提示词每次出的图都不同。
• quality:可以传,但不起作用,没有画质档位。
• 这些请求在建任务前就被拒绝,不扣费,也不会被悄悄忽略后照常出一张不符合要求的图。

价格

只有交付了图片才扣费;被 400 拒掉的请求不建任务、不扣费。带参考图不加价。计费示例:10 张 = $0.20,100 张 = $2.00。

常见报错

参数问题在创建时同步返回 400({"code": 400, "msg": "..."}),不会建任务、不扣费;一次调用模式下同样的报错以 OpenAI 的格式返回:{"error": {"message": "...", "type": "invalid_request_error"}}。下表 msg 是当前原文,括号和 got 里的值随你的请求变化。

• 401:API Key 缺失或无效。
• 402:余额不足以支付一张图($0.02)。
• 生成阶段的失败(内容被模型拒绝、临时的生成错误、超时)状态为 failed,原因在 data.failMsg,不扣费。见上方「不保证每次都成功」。

使用建议

• 要在图里出现文字,就把原文放进引号,并写明它在哪里(招牌、标题、标签)。Meta 介绍 Muse Image 的文字渲染很精确。 我们的一次测试里,黑板招牌上的「MUSE BOOKS」拼写正确;这只是一次测试,不是保证。
• 把构图写清楚:主体在哪、前景和背景是什么、左右各放什么。
• 图生图时写清楚哪些保留、哪些要改,例如「保留人物和位置,背景换成海滩,油画风格」。
• 传多张参考图时,说明每张图的用途,例如「以第一张图为底,把第二张图里的杯子放到桌上」。第 1 张是主图,要保留的那张放最前面。
• 参考图里的小字不一定能保留;出图里的大段文字只起装饰作用,可能有错字。需要准确的长文字,请出图后自己排版。
• 图生图时如果要保持主图的形状,就把 aspect_ratio 或 size 设成和主图相同的比例。
• 形状无所谓时留 auto;要放进固定版位(21:9 横幅、9:16 竖版)时再指定 aspect_ratio 或 size。
• 一次调用模式下,请求要等到出图才返回(测试中约 35-70 秒),HTTP 客户端超时至少设 2 分钟。
• 同一个提示词要多个版本时,并行发几个请求即可。
• 不要按请求的 size 假定像素,用 data.images 里的实际宽高做后续裁切或排版。

试一试:Playground。

相关