Grok Imagine 生图

Grok Imagine 生图只支持同步调用，一次请求直接返回图片的临时下载链接。

可用型号

三个型号的请求参数完全相同，只是单价不同。

请求参数

生成

quality、aspect_ratio、n 由模型校验，网关不查。grok-imagine-image-quality 是一个模型 ID，不是 quality 字段的取值。

size 是 GPT Image 的参数，Grok 生图不用它：画幅由 aspect_ratio 决定，像素档位由 resolution 决定。从 GPT Image 迁过来时，删掉 size，并把 quality 改成上面三个取值之一。

编辑

/v1/images/edits 在生成参数之外，用 image 传参考图：

• image 可以是 URL 字符串、字符串数组或 { "url": ... }。
• 每张是公开 HTTP(S) URL 或完整 Data URL（data:image/png;base64,…）。
• 不接受裸 base64、asset://、file_id。
• 用 OpenAI SDK 上传本机文件也可以：multipart 单张 image 或重复 image[] 文件。

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "把背景换成黄昏的海边，保留主体",
    "image": ["https://example.com/source.png"],
    "aspect_ratio": "3:2",
    "resolution": "1k"
  }'

画幅与实际出图尺寸

aspect_ratio 定形状，resolution 定像素总量：1k 约 100 万像素，2k 约 400 万像素。下表是 grok-imagine-image 在 resolution: 1k 下的实测出图尺寸：

9:19.5、20:9、9:20 同样是合法取值，上表未列它们的实测尺寸。resolution: 2k 保持同一形状、放大像素总量，例如 16:9 出 2816×1584、1:1 出 2048×2048。

返回结果

响应示例（URL 为占位符，其他 metadata 省略）：

{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

收到后请立即下载保存。响应不带 token 用量；空响应表示没有生成图片，不要把空 data 当成功。

示例

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "一只橘猫睡在洒满阳光的窗台上，杂志摄影风格",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

aspect_ratio 与 resolution 不是 OpenAI SDK 的内置参数，Python 里放进 extra_body。

注意事项

• 只支持同步：不支持流式，请勿发送 Prefer: respond-async 头。
• 生图的 resolution 只有 1k 与 2k，没有 4K 档，也不能填视频的 480p / 720p / 1080p。
• 返回的 URL 是临时链接，收到后请立即下载保存。
• 编辑最多 2 张参考图，这是 HopBase 的生图编辑限制，不适用于视频参考图。
• 生图与视频是两个分组、密钥不通用，视频见 Grok Imagine 视频。

常见报错

n、quality、aspect_ratio 超出范围时由模型自行拒绝并返回其消息。图片请求失败时检查 HTTP 状态及 error。

计费

按出图张数 × resolution 档计费，与像素宽高无关；/v1/images/edits 的每张参考图另计一笔，内容审核拒绝不计费。grok-imagine-image 传 2k 也会出图，按 1k 档单价计。

响应里的 usage.cost_in_usd_ticks 不是你的扣费，实际扣费以控制台「使用记录」为准。各档单价见上表模型卡，你的实际单价以模型广场为准。

下一步

• 图片总览：各生图系列的对比与通用规则
• GPT Image、Gemini 生图、Seedream：其他生图系列
• Grok Imagine 视频：Grok 视频任务的提交与轮询
• API 参考：生成图片、编辑图片
• 故障排查：请求失败时按症状排查