curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "身份验证失败,请检查您的API密钥",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "账户余额不足,请充值后再试",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "请求过于频繁,请稍后再试",
"type": "rate_limit_error"
}
}
Grok Imagine 2.0 Ext
Grok Imagine 2.0 Ext 图像生成
- 异步文生图,返回 task_id 轮询结果
- 单次 1–12 张,按实际成功张数计费($0.08/张)
- 仅支持 url 输出;不支持图生图 / 流式
- 图片链接有效期 72 小时
POST
/
v1
/
images
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "身份验证失败,请检查您的API密钥",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "账户余额不足,请充值后再试",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "请求过于频繁,请稍后再试",
"type": "rate_limit_error"
}
}
不要把 API Key 写进浏览器包(
VITE_* / NEXT_PUBLIC_*、LocalStorage 等)。推荐浏览器只调业务 BFF,由服务端持有 Key 调用本接口。curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "身份验证失败,请检查您的API密钥",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "账户余额不足,请充值后再试",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "请求过于频繁,请稍后再试",
"type": "rate_limit_error"
}
}
能力与限制
| 维度 | 说明 |
|---|---|
| 模型名 | 固定 grok-imagine-2.0-ext |
| 能力 | 仅文生图 |
| 调用方式 | 异步任务 |
张数 n | 1–12,默认 1 |
比例 size | 7 种比例 + 5 种兼容像素写法(见下) |
| 输出 | 仅 response_format=url(默认亦为 url) |
| 质量 | 对外字段为 resolution;已验证值 quality |
| 不支持 | 图生图、stream=true、quality 字段、style、b64_json / base64 |
| 计费 | 固定单价,按实际成功交付张数计费 |
认证与推荐 Header
string
必填
Bearer Token。访问 API Key 管理页面 获取。
Authorization: Bearer YOUR_API_KEY
| Header | 说明 |
|---|---|
Content-Type | application/json(提交) |
Accept | application/json |
Idempotency-Key | 强烈建议。每次「用户确认的一次逻辑生成」用新 UUID;网络重试必须复用同一 key 与 body |
X-APIMart-Response-Version | 推荐 2026-07-27,获得稳定的提交响应结构(data.id) |
请求参数
string
必填
固定值:
grok-imagine-2.0-extboolean
默认值:"false"
是否在提交图片任务前执行内容审核。
true:使用omni-moderation-latest审核提示词和输入图片false或不传:不发起审核请求,不增加审核成本与延迟(默认)
string
必填
提示词。去空格后不能为空。提交前请
trim。integer
默认值:"1"
生成张数:
1–12。显式传 0 会报错。未传按 1。string
画面比例。推荐使用比例写法(UI 建议只展示比例):
兼容像素写法:
size | 方向 | 典型用途 |
|---|---|---|
1:1 | 正方形 | 商品图、头像 |
2:3 | 竖图 | 海报、人物全身 |
3:2 | 横图 | 摄影、横向场景 |
3:4 | 竖图 | 电商、人物图 |
4:3 | 横图 | 展示图 |
9:16 | 竖屏 | 短视频封面、Story |
16:9 | 宽屏 | Banner、视频封面 |
1024x1024(1:1)、1024x1792(2:3)、1792x1024(3:2)、720x1280(9:16)、1280x720(16:9)。不在白名单内的值返回 400 invalid_size(如 1:2、2:1、4:5、auto)。同一比例下实际像素可能与兼容表不完全一致(例如
1:1 可能返回 1408×1408)。请以返回图片为准,不要反推改写 size。string
质量模式字段。当前已验证值:
quality。- 可省略(模型本身为质量模式)
- 或显式传
resolution: "quality"
1K / 2K / 4K 像素档;画面方向与比例由 size 控制。不要传公开字段
quality,会返回 400 invalid_quality。请使用 resolution。string
默认值:"url"
仅支持
url。可省略。传 b64_json / base64 会 400 invalid_response_format。明确不支持的参数
| 参数 | 行为 |
|---|---|
quality | 400 invalid_quality → 改传 resolution |
style | 400 invalid_style |
image_urls / image_with_roles | 400 invalid_image_input |
stream: true | 400 invalid_stream |
response_format: "b64_json" / "base64" | 400 invalid_response_format |
请求示例
最简
{
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图"
}
推荐
{
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上,干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}
提交响应
推荐携带X-APIMart-Response-Version: 2026-07-27。成功时 HTTP 202,任务 ID 在 data.id(不要依赖旧格式 data[0].task_id)。
请保存:
data.id:任务 ID,用于轮询request_id:排查网关问题- 本次
Idempotency-Key:结果不确定时安全重试 - 原始请求参数:展示与排查
幂等与安全重试
图片生成会计费,提交时强烈建议带Idempotency-Key(1–191 个可见 ASCII 字符,UUID 最省心;记录保留 24 小时)。
| 场景 | 表现 | 处理 |
|---|---|---|
| 同 key、同请求已完成 | 重放原响应,Header Idempotency-Replayed: true | 使用同一任务 ID |
| 同 key 仍处理中 | 409 idempotency_in_progress + Retry-After | 等待后用同 key、同 body 重试 |
| 同 key、不同参数 | 409 idempotency_key_reused | 新逻辑请求应换新 key |
| 原结果不确定 | 409 idempotency_result_indeterminate | 停止换 key,保留原 key 排查 |
查询任务
GET /v1/tasks/{task_id}?language=zh
Authorization: Bearer YOUR_API_KEY
Accept: application/json
language 可选:zh / en / ko / ja,仅影响失败文案本地化。详见 获取任务状态。
状态
status | 终态 | 处理 |
|---|---|---|
pending / processing | 否 | 继续轮询(进行中可能没有 result,不要判失败) |
completed | ✅ | 解析 result.images |
failed | ✅ | 展示 error.message;cost 为 0(预扣退款) |
unknown | 否 | 短暂重试;持续存在时带 task ID 联系支持 |
429 遵循 Retry-After。任务默认保留约 3 天,轮询超时后仍应保存 task ID。
完成态示例
{
"code": 200,
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"status": "completed",
"progress": 100,
"created": 1786419262,
"completed": 1786419275,
"actual_time": 13,
"estimated_time": 100,
"cost": 0.08,
"credits_cost": 0.8,
"result": {
"images": [
{
"expires_at": 1786505675,
"url": [
"https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
],
"image_ids": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}
]
}
}
}
解析 url 与 image_ids
result.images[]
├─ url[] ← 展示/下载的权威字段(数组)
├─ image_ids[] ← 可选,不透明 ID
└─ expires_at ← Unix 秒;前端倒计时需 ×1000
- 取图用
url[];n>1时遍历全部,不要只取第一张 - 仅当
image_ids.length === url.length时按下标配对 image_ids缺失不影响展示- 链接有效期 72 小时,请及时下载;同时以返回的
expires_at为准
计费
基础价 $0.08 / 张(按实际成功交付张数):n | 预计基础金额 |
|---|---|
| 1 | $0.08 |
| 4 | $0.32 |
| 8 | $0.64 |
| 12 | $0.96 |
- 下单前展示「预计」;任务完成后的
data.cost为最终美元金额 data.credits_cost为积分口径(当前约 = 美元 × 10)- 提交按请求张数预扣;最终按成功张数对账,部分失败退差额
- 整单失败:
cost=0,预扣退款 - 不要用
resolution拼价格档;本模型统一按张价
Webhook(可选)
{
"webhook": "https://your-service.example.com/apimart"
}
- 填 base URL,平台请求
{base}/callback - 须公网可访问并通过 SSRF 校验
- 若配置了
webhook_secret,签名为hex(HMAC-SHA256(secret, raw_body)),须用原始请求字节验签 - 回调体与任务查询的
data同源(不再包一层{code,data}) - 仍建议低频轮询兜底
常见错误
| HTTP | error.code | 原因 | 处理 |
|---|---|---|---|
| 400 | invalid_request | prompt 为空或 JSON 非法 | 校验输入 |
| 400 | invalid_n | n 不在 1–12 | 限制张数 |
| 400 | invalid_size | size 不在白名单 | 使用固定下拉 |
| 400 | invalid_response_format | 非 url | 固定或省略 |
| 400 | invalid_quality | 误传 quality | 改 resolution |
| 400 | invalid_style | 传了 style | 移除 |
| 400 | invalid_image_input | 传了参考图 | 换支持图生图的模型 |
| 400 | invalid_stream | stream=true | 移除 |
| 400 | invalid_idempotency_key | key 非法 | 使用 UUID |
| 401 | 鉴权失败 | Key 无效 | 服务端检查凭据 |
| 402 | 余额不足 | 余额不足 | 引导充值 |
| 409 | idempotency_* | 幂等冲突 | 见上文幂等表 |
| 429 | 限流 | 过快 | 按 Retry-After 退避 |
| 5xx | 服务异常 | — | 保留 Idempotency-Key,勿盲目换 key |
error.message。不要把鉴权细节或内部信息直接展示给终端用户。
与 1.5 的差异(摘要)
| 项 | Grok Imagine 1.5 | 2.0 Ext |
|---|---|---|
| 模型名 | grok-imagine-1.5-apimart 等 | grok-imagine-2.0-ext |
| 图生图 | 支持参考图编辑 | 不支持 |
| 张数 | 视 1.5 文档 | 1–12 |
| 质量字段 | 见 1.5 文档 | 用 resolution(quality),勿传 quality |
| 输出 | 见 1.5 文档 | 仅 url |
| 链接有效期 | 见 1.5 文档(常见 24h) | 72 小时 |
| 单价 | 见 1.5 文档 | $0.08 / 张 |