用一个统一接口，完成图片生成与图片编辑。

支持同步和异步两种调用方式。同步请求会等待图片生成完成后返回结果；异步请求会立即返回任务 ID，适合耗时较长的任务和自动化工作流。

开始之前

API 地址

https://api.maomaotoken.com

身份验证

每次提交和查询都需要携带 API 密钥：

Authorization: Bearer YOUR_API_KEY

请求和查询任务时，请使用同一账户下的 API 密钥。

选择调用方式

模式	工作方式	适用场景
同步	等待任务完成，直接返回图片结果	简单调用、短任务、人工调试
异步	立即返回任务 ID，随后查询任务状态	正式业务、长任务、自动化工作流

图片接口默认使用同步模式。只有明确传入 async=true 时，才会进入异步模式。

图片生成

根据文字描述生成图片。

同步生成

POST /v1/images/generations

curl https://api.maomaotoken.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "一只坐在窗边的橘猫",
    "n": 1,
    "response_format": "url"
  }'

请求会在图片生成完成后返回：

{
  "created": 1787155200,
  "data": [
    {
      "url": "https://api.maomaotoken.com/media/IMAGE_ID"
    }
  ]
}

异步生成

在原端点后增加 ?async=true：

POST /v1/images/generations?async=true

curl "https://api.maomaotoken.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "一只坐在窗边的橘猫",
    "n": 1,
    "response_format": "url"
  }'

提交成功后会立即返回网关任务 ID：

{
  "id": "task_xxxxxxxxxx",
  "status": "queued"
}

保存返回的 id，并将它作为 {task_id} 查询：

GET /v1/images/generations/{task_id}

curl https://api.maomaotoken.com/v1/images/generations/task_xxxxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

任务完成后，查询响应中的 data[].url 即为图片地址。

图片编辑

上传原图，并按照文字描述进行编辑。

同步编辑

POST /v1/images/edits

curl https://api.maomaotoken.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL" \
  -F "prompt=将背景改为雪山" \
  -F "image=@/path/to/image.png" \
  -F "response_format=url"

请求会在编辑完成后直接返回图片结果：

{
  "created": 1787155200,
  "data": [
    {
      "url": "https://api.maomaotoken.com/media/IMAGE_ID"
    }
  ]
}

异步编辑

在原端点后增加 ?async=true：

POST /v1/images/edits?async=true

curl "https://api.maomaotoken.com/v1/images/edits?async=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL" \
  -F "prompt=将背景改为雪山" \
  -F "image=@/path/to/image.png" \
  -F "response_format=url"

提交成功后保存返回的任务 ID，然后使用图片编辑查询端点：

GET /v1/images/edits/{task_id}

curl https://api.maomaotoken.com/v1/images/edits/task_xxxxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

任务完成后，查询响应中的 data[].url 即为编辑后的图片地址。

异步开启方式

以下三种写法都可以开启异步模式，任选一种即可。

URL 参数

?async=true

请求头

X-Async: true

请求参数

JSON 请求：

{
  "async": true
}

multipart/form-data 请求：

async=true

为了让调用行为更直观，推荐统一使用 URL 参数 ?async=true。

任务状态

异步任务通常会经历以下状态：

状态	含义
`queued` / `pending`	已接收，正在排队
`processing` / `in_progress` / `running`	正在处理
`completed` / `succeeded` / `success`	已完成，可以读取图片结果
`failed` / `cancelled`	任务失败或已取消

建议每隔 2–5 秒查询一次。只有任务成功后，才应读取和使用图片地址。

端点速查

能力	提交端点	查询端点
图片同步生成	`POST /v1/images/generations`	无需查询
图片异步生成	`POST /v1/images/generations?async=true`	`GET /v1/images/generations/{task_id}`
图片同步编辑	`POST /v1/images/edits`	无需查询
图片异步编辑	`POST /v1/images/edits?async=true`	`GET /v1/images/edits/{task_id}`

使用说明

model 必须填写账户当前可用的图片模型名称。
不同模型支持的尺寸、质量、图片数量和编辑参数可能不同。
图片编辑使用 multipart/form-data 上传文件，不要手动填写 Content-Type 边界。
异步查询必须使用提交响应中由网关返回的任务 ID。
图片生成与图片编辑使用各自的查询端点，请勿混用。
网络超时不一定代表任务失败。异步模式下，可继续使用任务 ID 查询最终状态。
请妥善保管 API 密钥，不要写入浏览器前端代码或公开仓库。

错误响应

请求失败时会返回 HTTP 状态码和错误信息：

{
  "error": {
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}

常见状态码：

状态码	含义
`400`	请求参数有误
`401`	API 密钥无效或未提供
`404`	任务不存在，或任务不属于当前账户
`429`	请求过于频繁或额度不足
`500–599`	服务暂时不可用，请稍后重试

图片 API