MoonNexAI API Docs

Appearance

GPT Image 异步调用 ​

GPT Image 异步接口适合生成时间较长、客户端不便持续保持 HTTP 连接，或需要在后台查询任务状态的场景。异步提交先返回 MoonNexAI 任务 ID，再通过任务查询接口读取状态和最终图片 URL。

本页只说明异步调用。需要在同一个 HTTP 请求中等待并直接获取图片结果时，请使用 GPT Image 同步调用。

异步入口 ​

能力路径说明
图片异步生成/v1/images/generations/async提交 prompt 并返回任务 ID。
图片异步编辑/v1/images/edits/async使用 JSON 图片 URL 或 Base64 Data URL 提交编辑任务。
查询任务/v1/images/tasks/{task_id}查询 status、progress、error 和成功结果。
获取内容/v1/images/tasks/{task_id}/content成功后获取第一张结果图片。

实际可用模型、单图或多图能力、图片数量和尺寸限制，以当前 API Key 所属分组和模型能力为准。

异步图片生成 ​

bash
curl https://moonnexai.com/v1/images/generations/async \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product mockup on a white studio table.",
    "size": "1024x1024",
    "n": 1
  }'

异步图片编辑 ​

异步图片编辑使用统一的 image 字段：单图传字符串，当前分组和模型支持多图时传字符串数组。

单图 URL：

bash
curl https://moonnexai.com/v1/images/edits/async \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留人物、姿势和服装，把画面改成水彩插画。",
    "image": "https://example.com/reference.png",
    "size": "1024x1024",
    "n": 1
  }'

多图 URL：

bash
curl https://moonnexai.com/v1/images/edits/async \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留第一张图的主体和构图，参考第二张图的色彩与细节。",
    "image": [
      "https://example.com/subject.png",
      "https://example.com/style.png"
    ],
    "size": "1024x1024",
    "n": 1
  }'

图片 URL 必须能被公网直接下载，建议使用带真实 .png、.jpg 或 .webp 后缀、无登录、无额外请求头和无短期签名的 HTTPS 地址。Base64 输入请使用完整 Data URL，例如 data:image/png;base64,...。

quality 是可选字段。未传时使用所选模型的默认质量行为；只有在已经确认当前模型支持目标质量档位时才显式传入。不同模型支持的质量值可能不同，不要为了表达“默认质量”主动补写 quality。

编辑字段 ​

字段说明
model必填。当前 API Key 分组可用的 GPT Image 模型名。
prompt必填。写清要保留的内容、要修改的区域和目标效果。
image编辑时必填。传一个图片 URL/Data URL 字符串，或在支持多图时传字符串数组。
size可选。输出尺寸，以所选模型支持范围为准。
quality可选。输出质量档位；省略时使用模型默认行为，显式值以所选模型支持范围为准。
n可选。生成数量，以模型和账户可用范围为准。

内容安全与失败处理 ​

图片输入和提示词都需要通过内容安全检查。任务可能因输入图片、人物描述、身体描写或其他提示词内容被拒绝；这类失败不表示图片 URL、多图数组或异步接口不可用。

当查询结果为 status=failed 时，读取 error.message，根据提示调整图片或提示词后创建新任务。失败任务不会产生结果 URL，不要继续轮询同一个任务，也不要把内容安全错误当成下载或网络错误处理。

提交响应 ​

提交成功后保存响应里的 id。不要把 queued 或 running 当成生成成功。

json
{
  "id": "task_xxx",
  "object": "image.edit",
  "created": 1711234567,
  "status": "queued",
  "progress": 0,
  "model": "gpt-image-2"
}

查询任务 ​

bash
curl https://moonnexai.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

查询时按以下顺序处理：

  1. 先检查 status。
  2. status=failed 时读取 error，不要继续等待结果 URL。
  3. status=queued 或 running 时继续轮询，并使用合理的查询间隔。
  4. 只有 status=succeeded 时才读取 data[].url。

成功响应示例：

json
{
  "id": "task_xxx",
  "object": "image.edit",
  "created": 1711234567,
  "status": "succeeded",
  "progress": 100,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://moonnexai.com/assets/public/v2/example/generated-image.png"
    }
  ]
}

异步结果始终以 URL 形式写入任务结果。需要下载第一张结果时，也可以请求 /v1/images/tasks/{task_id}/content 并按标准 HTTP 规则处理响应或重定向。

相关页面 ​