图像接口

MuskAPI 提供 OpenAI 兼容的图片生成和编辑接口。请先在用户中心创建 API Key，并确认该 Key 所在分组已开启“允许图片生成”，且模型列表中包含所需图片模型。

图片生成通常比文本请求耗时更长。生产客户端请将 HTTP 超时设置为至少 2 分钟，并控制并发数量。

Base URL 与认证

登录官网后，在“用户中心 - API 密钥”复制 Base URL。以下示例以 BASE_URL 表示该地址，所有请求均使用 Bearer API Key 认证。

BASE_URL="在用户中心 - API 密钥页面复制的 Base URL"
API_KEY="YOUR_MUSKAI_API_KEY"

先选择服务商

三类图片服务商的请求格式并不相同，不要只替换 model 后原样复用请求体。

服务商	当前常用模型	接口	关键差异
GPT-Image-2	`gpt-image-2`	`/v1/images/generations`、`/v1/images/edits`	OpenAI Images 格式；编辑使用 multipart 文件上传；支持 `quality`、`size`。
OpenAI 兼容 Nano Banana	`nano-banana-2`、`nano-banana-pro`	`/v1/images/generations`、`/v1/images/edits`	OpenAI Images 返回结构；使用 `aspect_ratio` 与 `resolution=1k/2k/4k`，不要发送 GPT Image 的 `quality` 或像素 `size`。
Grok	`grok-imagine-image`、`grok-imagine-image-quality`	`/v1/images/generations`、`/v1/images/edits`	使用 `aspect_ratio`；参考图通过 JSON `image_urls` 数组传入。
Gemini（Nano Banana / NoBanana）	`gemini-3.1-flash-image-preview`、`gemini-3-pro-image-preview`	`/v1beta/models/{model}:generateContent`	Gemini 原生 `contents` 格式；比例与分辨率放在 `generationConfig.imageConfig`；图片从 `inlineData` 读取。

模型会随上游供应和分组配置变化。正式接入前请在模型广场确认模型仍然公开，并确认 API Key 所属分组覆盖该模型。

nano-banana-2 / nano-banana-pro 是 OpenAI Images 兼容模型，与下文使用 Gemini 原生 generateContent 的 Gemini Nano Banana 是两种不同调用方式。请根据模型 ID 选择协议。

GPT-Image-2 教程

文生图

路径：POST /v1/images/generations

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只穿宇航服的橘猫，漂浮在木星轨道，电影感光影",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1,
    "response_format": "b64_json"
  }'

GPT-Image-2 常用参数：

参数	说明
`model`	图片模型名称；以控制台当前开放的模型为准。
`prompt`	图片描述。建议明确主体、构图、风格、光线和文字要求。
`size`	尺寸或模型支持的尺寸档位。可用值取决于模型和通道。
`quality`	常见值为 `low`、`medium`、`high`；部分模型支持 `auto`。质量和尺寸会影响价格。
`n`	生成张数。按实际返回的图片张数计费，并受 API Key/订阅配额限制。
`response_format`	需要内嵌图片时使用 `b64_json`；部分上游也可能返回临时 `url`。客户端应同时兼容两种结果。

成功响应遵循 OpenAI Images 结构，图片位于 data 数组中：

{
  "created": 1770000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA...",
      "revised_prompt": "..."
    }
  ]
}

图片编辑 / 参考图生成

路径：POST /v1/images/edits

使用 multipart/form-data 上传参考图；不要手工设置 Content-Type，由 HTTP 客户端自动填入 boundary。

curl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=保留人物姿势，将背景改为雨夜霓虹城市，写实电影风格' \
  -F 'size=1024x1024' \
  -F 'quality=medium' \
  -F 'response_format=b64_json' \
  -F 'image=@./reference.png;type=image/png'

是否支持多张参考图、蒙版、透明背景及具体尺寸，取决于模型和当前上游通道。单张参考图请控制在 20 MB 以内；请求被拒绝时，请先检查模型能力、图片格式和参数组合。

不要给 multipart 请求手工添加 Content-Type: multipart/form-data；否则会缺少 boundary。若需要多张参考图，可重复传入 -F 'image=@...'，当前网关最多接受 4 个参考图 URL/上传项，但最终数量仍受所选上游限制。

网关兼容：在 generations 请求中携带参考图

如果客户端只能发送 JSON，也可以调用 /v1/images/generations 并使用本平台扩展字段 image_urls。网关会将请求自动转换为上游标准 /v1/images/edits multipart 请求；该字段不是 OpenAI 官方参数。每项应为公网 HTTPS 图片地址或 data:image/png|jpeg|webp;base64,...，最多 4 张、每张解码后不超过 20 MB。

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留猫的姿态，将背景改为木星上空的电影感场景",
    "image_urls": ["data:image/png;base64,BASE64_IMAGE_DATA"],
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

使用官方 OpenAI 端点时请勿发送 image_urls，应使用上一节的 /v1/images/edits 文件上传格式。

OpenAI 兼容 Nano Banana 教程

nano-banana-2 和 nano-banana-pro 使用 /v1/images/generations，响应与 GPT Image 相同，图片位于 data[0].b64_json 或 data[0].url。两者使用画幅与分辨率档位，不使用 GPT Image 的 quality 或具体像素 size。

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "电影感城市夜景，清晰建筑细节，蓝紫色霓虹灯",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1,
    "response_format": "b64_json"
  }'

切换为 nano-banana-pro 只需替换 model。当前常用分辨率档位为 1k、2k、4k；画幅以模型广场展示为准。客户端必须同时处理以下两种成功结果：

{"data":[{"b64_json":"BASE64_IMAGE_DATA"}]}

{"data":[{"url":"https://temporary.example/result.png"}]}

url 通常是临时地址，应立即下载保存。HTTP 200 但 data 中没有非空 b64_json 或 url 时，应按生成失败处理。

Grok 教程

快速文生图

grok-imagine-image 偏快速，grok-imagine-image-quality 偏质量。Grok 的画幅使用 aspect_ratio，不要照搬 GPT-Image-2 的像素 size。

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "未来东京雨夜的拉面店，纪实摄影，霓虹灯反射",
    "aspect_ratio": "16:9",
    "response_format": "b64_json"
  }'

当前模型广场显示 Grok 支持多种画幅，例如 1:1、16:9、9:16、4:3、3:4、3:2 和 2:3。不要发送视频接口才使用的 duration。分辨率和价格档位由具体模型/通道决定；需要质量档时优先选择 grok-imagine-image-quality，不要假设 quality=high 会把快速模型切换为质量模型。

使用参考图编辑

Grok 参考图使用 JSON image_urls。可以传公网 HTTPS URL，也可以传 data:image/...;base64,...；最多 4 张，每张解码后不超过 20 MB。

curl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "保留主体，把场景改为雪山日出",
    "aspect_ratio": "16:9",
    "image_urls": ["https://example.com/reference.png"],
    "response_format": "b64_json"
  }'

如果应用本身已经有图片 URL，建议直接由程序构造 JSON，不要在 Shell 中拼接大型 Base64。服务端程序应同时兼容返回项中的 b64_json 和临时 url。

Gemini（Nano Banana / NoBanana）教程

Gemini 图片模型不使用 OpenAI Images 请求体。下面以当前公开的 gemini-3.1-flash-image-preview 为例；也可按模型广场替换为 gemini-3-pro-image-preview。

文生图

GEMINI_MODEL="gemini-3.1-flash-image-preview"

curl "$BASE_URL/v1beta/models/$GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "一张极简产品海报：白色陶瓷香水瓶，柔和侧光，米色背景"}]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "4:5",
        "imageSize": "2K"
      }
    }
  }'

Gemini 字段使用驼峰命名：responseModalities、imageConfig.aspectRatio、imageConfig.imageSize。当前公开能力包含 1K、2K、4K 等分辨率以及 1:1、16:9、9:16、4:5 等画幅；必须以所选模型在模型广场显示的能力为准。

使用参考图

参考图放在同一个 parts 数组中。inlineData.data 只填纯 Base64，不要带 data:image/png;base64, 前缀。

{
  "contents": [{
    "parts": [
      {"text": "保留产品造型，把背景改成深蓝色星空"},
      {"inlineData": {"mimeType": "image/png", "data": "BASE64_WITHOUT_PREFIX"}}
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
  }
}

成功响应中的图片通常位于：

candidates[0].content.parts[*].inlineData.data

同时读取 inlineData.mimeType 作为文件类型。某些兼容实现可能使用蛇形字段 inline_data / mime_type，稳健的客户端可同时兼容两种命名。若响应只含文本或安全拦截信息，不要把请求当作成功图片。

通用返回处理

GPT-Image-2 / Grok：遍历 data 数组，优先读取 b64_json，否则下载 url；临时 URL 应立即保存。
Gemini：遍历所有 candidates[].content.parts[]，寻找 inlineData.data，不要只读取第一个 part。
Base64 结果可能很大。生产环境应提高响应体限制，避免将完整 Base64 写入普通应用日志。
HTTP 200 不一定代表拿到了图片；只有解析出非空图片内容后才应标记任务完成。

异步图片任务（兼容接口）

对于支持异步任务的上游，可使用以下兼容接口创建任务：

POST /v1/images/tasks

curl "$BASE_URL/v1/images/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "极简风格的山间咖啡馆海报",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

从创建响应中取出 task_id（部分上游字段名可能为 id），随后轮询：

curl "$BASE_URL/v1/images/tasks/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

注意：

这是对上游异步图片任务 API 的兼容透传，不是 MuskAPI 自建的离线任务队列；只有声明支持异步图片任务的上游通道可以使用。
创建任务后，平台会在短期内将任务 ID 绑定回原上游账号，查询时请使用创建任务的同一 API Key/分组。当前绑定最长保留 24 小时；超过该时间，或原账号不可用时，历史任务可能无法继续查询。
请根据响应中的任务状态轮询，建议间隔 2 到 5 秒；完成后立即下载或保存结果。
不要假设每个服务商都支持该接口。Gemini 原生 generateContent 和普通 Grok Images 请求应按同步响应处理；只有模型/通道明确声明异步任务能力时才调用 /v1/images/tasks。

图片保存与历史记录

网页“AI 图片生成”页的最近图片和待处理队列目前是浏览器本地的尽力保存：优先使用 IndexedDB，失败时会降级为 localStorage。因此它存在以下限制：

不会在浏览器、设备或登录节点之间同步。
隐私模式、浏览器存储空间不足、清理站点数据或写入失败时，历史图片可能不显示或丢失。
当前服务端旧作品图库依赖节点本机磁盘；在多机部署下没有统一共享存储与一致性保障，不能作为可靠的云端图片库使用。
平台当前不提供图片 OSS 保存、保存时长配置、自动生命周期删除，或向用户收取 OSS 容量/流量费用的能力。

请在图片生成成功后立即下载并自行备份原图。 不要把网页历史、上游临时 URL 或当前服务端作品库当作长期存储。

常见问题

返回“Image generation is not enabled for this group”

该 API Key 所在分组未开启图片生成权限。请更换已启用图片生成的 API Key，或联系管理员调整分组配置。

返回“无可用兼容账号”或模型不存在

当前分组没有支持该模型、尺寸、质量或接口类型的可用上游通道。请在模型列表确认模型名称和开放能力，或降低尺寸/质量后重试。

返回参数错误或请求成功但没有图片

先确认没有混用服务商格式：GPT 编辑必须是 multipart；Grok 使用 aspect_ratio 和 JSON image_urls；Gemini 使用原生 contents / generationConfig，并从 inlineData 读取结果。还应检查画幅、分辨率和模型 ID 是否出现在模型广场当前能力中。

超时或客户端中途断开

将客户端、反向代理和 SDK 超时统一提高到至少 120 秒；高分辨率或多张生成建议更长。不要在超时后立刻无限重试，否则原请求仍在上游运行时可能产生重复图片和重复计费。

生成成功但网页历史里找不到图片

浏览器本地存储并非可靠持久化。请优先从本次响应的 b64_json 或 url 下载图片；如已关闭页面或清理浏览器数据，平台无法保证恢复该图片。

Base URL 与认证​

先选择服务商​

GPT-Image-2 教程​

文生图​

图片编辑 / 参考图生成​

网关兼容：在 generations 请求中携带参考图​

OpenAI 兼容 Nano Banana 教程​

Grok 教程​

快速文生图​

使用参考图编辑​

Gemini（Nano Banana / NoBanana）教程​

文生图​

使用参考图​

通用返回处理​

异步图片任务（兼容接口）​

图片保存与历史记录​

常见问题​

返回“Image generation is not enabled for this group”​

返回“无可用兼容账号”或模型不存在​

返回参数错误或请求成功但没有图片​

超时或客户端中途断开​

生成成功但网页历史里找不到图片​