异步接口（推荐）

根据文字提示词生成图片，或结合参考图片进行编辑。

提交请求后获取任务编号，再通过查询接口获取任务状态和最终结果，无需在整个生成过程中保持同一条 HTTP 连接。

新项目接入建议优先使用异步接口。

适用于长耗时图片生成、批量处理、后台任务，以及需要展示生成状态的应用。

异步调用可以减少长连接等待带来的超时问题，但不会缩短模型本身的生成时间。

https://api.maomaotoken.com

创建和查询任务时，均需携带 API Key，建议使用创建任务时的同一密钥：

Authorization: Bearer YOUR_API_KEY

将 YOUR_API_KEY 替换为 MaoMaoToken 提供的实际密钥，保留 Bearer 前缀及其后的空格。

以下路径均需拼接到 Base URL 之后。

提交图片生成或编辑请求时，通过以下任意一种方式启用异步调用，无需重复设置。

设置位置	写法
JSON 请求体	添加 `"async": true`，其中 `true` 为布尔值，不加引号
URL 查询参数	在创建端点后添加 `?async=true`；已有查询参数时使用 `&async=true`
请求头	添加 `X-Async: true`
Multipart 表单	添加字段 `async`，字段值为 `true`

模型名称、提示词、参考图片和其他参数，以对应模型文档为准。
JSON 请求使用 Content-Type: application/json。文件上传仅在模型支持时使用 multipart/form-data，由 HTTP 客户端自动生成包含 boundary 的完整请求头。
创建成功后，响应中会包含任务编号 id 和当前状态 status；部分响应还会包含 task_id。请保存 id 及任务类型，用于后续查询。
创建成功表示任务已提交，不代表图片已经生成完成，请通过对应的查询接口获取任务状态和最终结果。

根据创建任务时使用的端点，选择对应的查询接口。

查询采用 GET 请求，无需提交 JSON 请求体，也无需重复发送提示词、参考图片或其他生成参数。

将示例中的 YOUR_TASK_ID 替换为创建响应中的 id，将 YOUR_API_KEY 替换为创建任务时使用的 API Key。

查询文生图任务

适用于通过 POST /v1/images/generations 创建的异步任务。

GET /v1/images/generations/{task_id}

请求示例：

curl --request GET \
  "https://api.maomaotoken.com/v1/images/generations/YOUR_TASK_ID" \
  --header "Authorization: Bearer YOUR_API_KEY"

查询图片编辑任务

适用于通过 POST /v1/images/edits 创建的异步任务。

GET /v1/images/edits/{task_id}

请求示例：

curl --request GET \
  "https://api.maomaotoken.com/v1/images/edits/YOUR_TASK_ID" \
  --header "Authorization: Bearer YOUR_API_KEY"

查询频率

建议每 3～5 秒 查询一次，长时间等待时可适当增加间隔。取得最终图片结果，或确认任务失败、取消后，应停止轮询。

单次查询超时或临时网络异常时，可以使用同一任务编号稍后重试查询，无需重新创建任务。

判断任务状态

不同模型可能返回不同的状态名称，常见取值如下，具体以对应模型文档为准。

任务阶段	常见状态值	处理方式
排队中	queued、pending	等待后继续查询
处理中	processing、in_progress、running	等待后继续查询
生成成功	completed、succeeded、success	检查响应中是否已提供可用图片结果
失败或取消	failed、cancelled、canceled	停止轮询，记录失败信息

HTTP 200 只表示本次提交或查询请求成功，不能单独作为图片生成成功的依据。

请同时检查任务状态和结果；若状态已成功但图片结果尚未就绪，应间隔后继续查询，不要重复创建任务。

progress 如有返回，仅用于进度展示。

任务失败也可能通过非 2xx HTTP 响应及错误对象返回，不一定包含 status 字段。

请结合响应内容判断原因：临时网络或服务异常可稍后重试查询，明确的任务失败应停止轮询。

若长时间没有结果，请保留任务编号并联系技术支持。

实际返回结构以模型文档为准，不保证同时包含 url 和 b64_json。取得最终结果后停止轮询，图片地址可能具有有效期，请及时下载保存。

提交和查询请求仍需配置合理的客户端、程序及代理超时。创建请求超时且未收到任务编号时，不能据此认定任务未提交成功，请避免立即重复创建。
获得任务编号后，单次查询超时或临时网络异常可稍后重试查询，无需重新提交生成请求。鉴权失败等明确错误应先处理原因；任务明确失败或取消后应停止轮询。
建议将任务编号保存在服务端，以便页面刷新或客户端重新连接后继续查询。排查问题时，请提供任务编号、调用时间、模型名称及响应头中的 X-Oneapi-Request-Id。