异步图片生成与编辑任务

所有请求都要携带 API Key

在请求头中放入 MaolaoAPI 令牌。示例里的密钥只是占位符，不要把真实密钥写进前端源码或公开仓库。

Authorization: Bearer sk-你的API_KEY

任务归属于令牌对应的账号。同一账号下的其他有效令牌可以查询任务，其他账号会得到 404 task not found。

图片生成请求示例

不传 action 时，默认创建图片生成任务。请求体与 /v1/images/generations 保持兼容。

curl -X POST "https://maolaoapi.com/v1/images/tasks" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-enterprise",
    "prompt": "一只坐在月球上的橘猫，电影级光影",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "b64_json"
  }'

成功接收

{
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued"
}

图片模型支持尺寸

请求时直接传 MaolaoAPI 对外模型名即可。下面列出当前常用 GPT 图片模型的 size 支持情况，其中 gpt-image-2-4K 是既有 4K 档位模型。

{
  "model": "grok-imagine-image",
  "prompt": "一辆停在雨夜街角的复古跑车",
  "extra_fields": {
    "resolution": "2k",
    "aspect_ratio": "16:9"
  },
  "response_format": "b64_json"
}

图片生成参数说明

单图输入编辑

把 action=edits 放在查询参数中。图片编辑任务使用同一个对外模型名。

curl -X POST "https://maolaoapi.com/v1/images/tasks?action=edits" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -F "model=gpt-image-2-enterprise" \
  -F "prompt=把背景替换成夜晚的东京街道" \
  -F "image=@input.png" \
  -F "size=1024x1024" \
  -F "quality=high"

异步执行可以避免等待生成结果时的 HTTP 超时，但不能绕过请求体大小限制。

多图输入编辑

可以重复传 image 字段上传多张图片。不同模型的输入图数量上限不同，超出上限会返回错误。

curl -X POST "https://maolaoapi.com/v1/images/tasks?action=edits" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -F "model=gpt-image-1.5-enterprise" \
  -F "prompt=合并两张图的主体，保持自然光照" \
  -F "image=@input-a.png" \
  -F "image=@input-b.png" \
  -F "size=1024x1024" \
  -F "quality=medium"

使用 task_id 查询状态

curl "https://maolaoapi.com/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-你的API_KEY"

{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "expires_at": 1784200000,
  "result": {
    "created": 1784196400,
    "data": [
      {
        "url": "/v1/images/tasks/task_xxx/content/0",
        "revised_prompt": "..."
      }
    ]
  }
}

下载受保护的图片内容

如果 result.data[].url 以 /v1/ 开头，请拼接 API 域名，并继续携带 Bearer Token。

curl "https://maolaoapi.com/v1/images/tasks/task_xxx/content/0" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -o result.png

提交任务并等待生成完成

const baseURL = 'https://maolaoapi.com'
const apiKey = 'sk-你的API_KEY'

async function createImageTask() {
  const response = await fetch(`${baseURL}/v1/images/tasks`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-image-2-enterprise',
      prompt: '一座漂浮在云海上的未来城市',
      size: '1024x1024',
      quality: 'high',
      n: 1,
      response_format: 'b64_json',
    }),
  })

  if (!response.ok) throw new Error(await response.text())
  return response.json()
}

async function waitForTask(taskId) {
  while (true) {
    const response = await fetch(
      `${baseURL}/v1/images/tasks/${encodeURIComponent(taskId)}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    )

    if (!response.ok) throw new Error(await response.text())
    const task = await response.json()

    if (task.status === 'succeeded') return task.result
    if (task.status === 'failed') {
      throw new Error(task.error || '图片生成失败')
    }

    await new Promise((resolve) => setTimeout(resolve, 2500))
  }
}

Imagen 可以使用同一条异步路径

请求体仍然采用 OpenAI Images 格式。当前 Gemini 图片适配器支持最终模型名称以 imagen 开头的模型。

curl -X POST "https://maolaoapi.com/v1/images/tasks" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-generate-001",
    "prompt": "赛博朋克风格的重庆夜景",
    "n": 1,
    "size": "16:9",
    "quality": "2K",
    "response_format": "b64_json"
  }'

同时处理 HTTP 状态和任务状态

{
  "error": {
    "message": "task not found",
    "type": "invalid_request_error"
  }
}

图片正文默认保留 1 小时

到期后任务状态和审计记录仍然保留，但图片正文无法继续读取。

{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "result_expired": true,
  "expires_at": 1784200000
}

当前限制

• 暂不提供取消任务接口。
• 暂不提供完成回调或 Webhook。
• 暂不提供公开的任务列表接口。
• ?group=xxx 不能覆盖 API Key 对应的分组。
• 固定按张计费以实际可交付数量结算，最多不超过请求的 n。