MoonApiX Docs

Appearance

图片异步任务 ​

图片异步接口用于提交可能耗时较长的图片生成或编辑任务。同步 /v1/images/generations 和 /v1/images/edits 会一直等待生成完成；异步接口会先返回任务 ID，客户端随后轮询查询结果。

接口路径 ​

方法路径用途
POST/v1/images/generations/async创建图片异步生成任务。
POST/v1/images/edits/async创建图片异步编辑任务。
GET/v1/images/tasks/{task_id}查询图片异步任务。
GET/v1/images/tasks/{task_id}/content任务成功后跳转到结果图片。

创建生成任务 ​

bash
curl https://moonapix.com/v1/images/generations/async \
  -H "Authorization: Bearer <MOONAPIX_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
  }'

响应：

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

创建编辑任务 ​

图片异步编辑使用 JSON 请求，适合传公网图片 URL 或 Base64 图片内容。需要直接上传本地文件时，请使用同步 /v1/images/edits。

bash
curl https://moonapix.com/v1/images/edits/async \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-pro",
    "prompt": "Change the background to a clean studio scene.",
    "image": "https://example.com/product.png",
    "size": "1024x1024"
  }'

查询任务 ​

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

处理中：

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "running",
  "progress": 30,
  "model": "gpt-image-2"
}

成功：

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "succeeded",
  "progress": 100,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://media.moonapix.com/image/example.png"
    }
  ]
}

失败：

json
{
  "id": "task_xxx",
  "object": "image.generation",
  "created": 1711234567,
  "status": "failed",
  "progress": 100,
  "model": "gpt-image-2",
  "error": {
    "code": "image_task_failed",
    "message": "Image task failed. Please check prompt, input image, and size."
  }
}

状态说明 ​

状态含义处理方式
submitted任务已提交。稍后继续查询。
queued任务排队中。稍后继续查询。
running正在生成。继续轮询，建议 3 到 10 秒一次。
succeeded任务成功。读取 data[].url，或访问 content 路径。
failed任务失败。读取 error.message，调整参数后重试。

获取图片内容 ​

任务成功后可以访问：

http
GET /v1/images/tasks/{task_id}/content

该接口会跳转到结果图片 URL，适合浏览器预览或下载场景。API 集成仍建议优先查询任务并保存 data[].url。

同步与异步选择 ​

场景推荐接口
希望一次请求直接拿到图片结果，且客户端可等待。/v1/images/generations 或 /v1/images/edits
任务可能较慢、客户端不稳定、网关有超时限制。/v1/images/generations/async 或 /v1/images/edits/async
需要上传本地图片文件做编辑。/v1/images/edits
编辑输入已经是公网 URL 或 Base64 图片内容。/v1/images/edits/async

同步请求中途断开时，客户端通常拿不到最终响应；请改用异步接口保存任务 ID 后再查询。

异步图片模型 ​

这些模型推荐直接使用 /v1/images/generations/async 创建任务，并通过 /v1/images/tasks/{task_id} 查询结果：

模型常用模式推荐尺寸写法结果
seedream-5.0文生图、图生图size，例如 2048x2048 或 2048*2048data[].url
seedream-4.5文生图、图生图size，例如 2048x2048 或 2048*2048data[].url
wan2.7-image-pro文生图、图生图size 或模型支持的比例参数data[].url

图生图时可以在请求中传入公网图片 URL 或 MoonApiX 托管 URL。图片需要能够被模型访问，建议原图至少 300x300，并避免使用需要登录、短期过期或禁止抓取的地址。

模型参数、尺寸和单次生成数量以 MoonApiX 后台、价格页和 GET /v1/models 为准。完整示例见 Seedream / Wan 异步图片模型。

结果格式 ​

图片异步任务成功后返回 URL。即使生成过程中得到的是图片内容，MoonApiX 也会转换成可访问的 URL 后写入 data[].url，不会在任务结果里返回图片 Base64 正文。

相关页面 ​