Grok Imagine 2.0 Ext 图像生成

• 异步文生图，返回 task_id 轮询结果
• 单次 1–12 张，按实际成功张数计费（$0.08/张）
• 仅支持 url 输出；不支持图生图 / 流式
• 图片链接有效期 72 小时

请求示例

bash curl --request POST \ --url https://api.openveer.com/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-OpenVeer-Response-Version: 2026-07-27' \ --data '{ "model": "grok-imagine-2.0-ext", "prompt": "一只红苹果放在白色陶瓷盘上，干净的棚拍产品图", "n": 1, "size": "1:1", "resolution": "quality", "response_format": "url" }'

```python
import requests
import uuid

url = "https://api.openveer.com/v1/images/generations"

payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "一只红苹果放在白色陶瓷盘上，干净的棚拍产品图",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}

headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-OpenVeer-Response-Version": "2026-07-27",
}

response = requests.post(url, json=payload, headers=headers)

print(response.status_code, response.json())
```

```javascript
const url = "https://api.openveer.com/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 ",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-OpenVeer-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));
```

响应示例

json { "code": 202, "request_id": "2026081111342261665927mpb4IPDb", "data": { "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX", "object": "generation.task", "type": "image", "status": "pending", "progress": 0, "poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX" } }

json { "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" } }

json { "error": { "code": 401, "message": "身份验证失败，请检查您的API密钥", "type": "authentication_error" } }

json { "error": { "code": 402, "message": "账户余额不足，请充值后再试", "type": "payment_required" } }

json { "error": { "code": 429, "message": "请求过于频繁，请稍后再试", "type": "rate_limit_error" } }

能力与限制

认证与推荐 Header

请求参数

明确不支持的参数

请用白名单组装请求，不要把其他图片模型的表单对象整体透传。

请求示例

最简

{
  "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-OpenVeer-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 小时）。

POST 网络超时、无法判断是否已创建任务时，不要立刻换新 key；用相同 key / body / 响应版本重试。

查询任务

GET /v1/tasks/{task_id}?language=zh
Authorization: Bearer YOUR_API_KEY
Accept: application/json

language 可选：zh / en / ko / ja，仅影响失败文案本地化。详见 获取任务状态。

状态

建议约每 2 秒查一次；最长约 10 分钟或 120 次。遇 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

1. 取图用 url[]；n>1 时遍历全部，不要只取第一张
2. 仅当 image_ids.length === url.length 时按下标配对
3. image_ids 缺失不影响展示
4. 链接有效期 72 小时，请及时下载；同时以返回的 expires_at 为准

计费

基础价 \$0.08 / 张（按实际成功交付张数）：

• 下单前展示「预计」；任务完成后的 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}）
• 仍建议低频轮询兜底

常见错误

错误提示优先用 error.message。不要把鉴权细节或内部信息直接展示给终端用户。

与 1.5 的差异（摘要）