Skip to main content
POST
异步图片接口。 提交成功后返回任务 ID,请通过获取任务状态接口轮询最终结果。 不传 image_urls 即文生图;传入 image_urls 即图片编辑或多图参考。
不要把长期有效的 APIMart API Key 写入浏览器代码、VITE_* / NEXT_PUBLIC_*、LocalStorage、URL 或前端日志。生产环境应由业务后端或 BFF 持有 API Key 并调用本接口。

接入概览

异步任务

提交后返回任务 ID,通过任务状态接口获取最终结果。

生成与编辑

一个接口同时支持文生图、单图编辑和多图参考。

统一轮询

使用返回的 data.id 请求任务状态接口,直到任务完成或失败。
提交成功时 HTTP 状态为 202,任务 ID 位于 data.id。使用 data.poll_urlGET /v1/tasks/{task_id} 轮询任务状态。

模型能力

quality 的发送规则:
  • 可选 lowmedium,默认 medium
  • 请求含参考图时不要发送 quality
  • 添加参考图时,应清除表单中遗留的 quality

Authorizations

string
必填
所有接口均使用 Bearer Token 认证。访问 API Key 管理页面 获取 API Key,并在请求头中添加:

推荐请求头

Body

string
默认值:"grok-imagine-image-2.0"
必填
固定值:grok-imagine-image-2.0
string
必填
图片生成或编辑的文本描述。去除首尾空格后不能为空,最多 8000 个字符。多图参考时,可以按数组顺序在提示词中使用 <IMAGE_0><IMAGE_1><IMAGE_2> 引用图片。
integer
默认值:"1"
输出图片张数,取值为 110
string
默认值:"auto"
图片宽高比。支持:允许值完整列表:1:13:44:39:1616:92:33:29:19.519.5:99:2020:91:22:1auto
新接入不要发送像素尺寸字符串。画面比例由 aspect_ratio 控制,清晰度档位由 resolution 控制。
string
默认值:"1k"
图片清晰度档位:
  • 1k(默认)
  • 2k
string
grok-imagine-image-2.0 文生图支持:
  • low
  • medium(2.0 文生图默认)
请求包含 image_urls 时不要发送本字段。
array
参考图片数组,允许 13 张。省略本字段即文生图。数组元素支持:
  1. 公网可访问的绝对 http://https:// URL;
  2. JPEG、PNG、WebP 的 Base64 Data URL。
Data URL 示例:
  • 不接受相对 URL、裸 Base64 或其它格式的 Data URL;
  • Data URL 解码后单张不超过 10 MiB;
  • 数组顺序会保留;
  • 重复图片按多张输入处理并按张计费;
  • 没有参考图时应省略本字段,不要发送空数组。

使用示例

2.0 文生图

单图编辑

有参考图时不要发送 quality

多图参考

Response

integer
HTTP 业务状态码,提交成功时为 202
string
本次请求的排查 ID。联系支持或记录错误时请保留。
string
任务 ID,用于查询任务状态。
string
异步任务固定为 generation.task
string
提交成功时为 pending
integer
提交时通常为 0
string
任务查询路径。也可使用 GET /v1/tasks/{task_id} 查询。
轮询直到任务进入 completedfailed。完整字段请参阅获取任务状态

上传本地参考图

如果用户选择本地文件,可先上传到平台,再把返回的 url 放入生成请求的 image_urls
表单字段固定为 file
成功响应:
  • 支持 JPEG、PNG、WebP;
  • 单张图片不超过 10 MiB;
  • 使用 FormData 时不要手动设置 Content-Type,客户端会自动添加 multipart boundary。

获取预估价格

价格应以报价接口返回的 final_usd 为准,不要在客户端硬编码价格或自行计算最终金额。

报价参数

示例:
不要用 unit_price_usd × image_count + input_surcharge_usd 替代 final_usd。用户折扣、分组价格和整单取整可能使自行计算的结果不同。
输入图片从第 1 张开始计费,费用按输入张数计算,不再乘输出数量 n。前端只需把 image_urls.length 作为 input_images,并展示报价返回的 final_usd 需要读取当前 Web 登录用户的个性化报价时,请携带 Session Cookie:
模型、naspect_ratioresolutionquality 或参考图数量变化后,应重新报价。建议使用 200–300ms 防抖,并取消上一笔未完成的请求,防止旧响应覆盖新价格。

幂等与重试

图片生成会产生费用。每次用户确认的一次逻辑生成都应创建一个 Idempotency-Key
  1. 首次请求创建一个 UUID;
  2. 同一次请求的网络重试复用原 UUID 和完全相同的请求 Body;
  3. 修改模型、提示词、图片或其它参数后创建新 UUID;
  4. 不要在每次自动重试时创建新 UUID;
  5. 同一 Key 重试时,X-APIMart-Response-Version 也必须保持一致。
浏览器取消请求只表示客户端不再等待响应,不代表服务端生成已经取消,也不代表一定不会计费。

错误处理

统一错误结构:
建议记录 request_idIdempotency-Key、模型名、HTTP 状态和错误 code。不要记录 API Key、完整 Data URL、用户隐私图片或包含敏感信息的完整提示词。

TypeScript 服务端封装

以下代码应运行在业务后端或 BFF,不要放入包含长期 API Key 的浏览器产物。
提交成功后,使用返回的 taskId 调用获取任务状态,直到任务状态变为 completedfailed

前端联动规则

最小上线要求:
  1. 固定调用 POST /v1/images/generations
  2. 固定发送 X-APIMart-Response-Version: 2026-07-27
  3. 每次逻辑生成创建一个幂等 Key,重试时复用;
  4. 参考图统一通过 image_urls 传入,最多 3 张;
  5. 尺寸统一使用 aspect_ratio + resolution
  6. 从提交响应中读取任务 ID;
  7. 使用报价接口的 final_usd 展示预估价格;
  8. 通过任务状态接口轮询至 completedfailed