Grok Imagine 生图
用 Grok Imagine 生成和编辑图片:参数、返回与注意事项。
| 项目 | 值 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 生成图片 | POST /v1/images/generations |
| 编辑图片 | POST /v1/images/edits |
| 分组 | 「Grok 全系」 |
Grok Imagine 生图只支持同步调用,一次请求直接返回图片的临时下载链接。
可用型号
| 型号 | 模型 ID | 档位 | 官方价 |
|---|---|---|---|
| Grok Imagine Image | grok-imagine-image | 1k / 2k | $0.02/ 张 |
| Grok Imagine Image 2.0 | grok-imagine-image-2.0 | 1k / 2k | $0.04起/ 张 |
| Grok Imagine Image Quality | grok-imagine-image-quality | 1k / 2k | $0.05起/ 张 |
三个型号的请求参数完全相同,只是单价不同。
请求参数
生成
| 参数 | 必填 | 类型与限制 | 默认 | 说明 |
|---|---|---|---|---|
model | 必填 | string,上表三个 ID 之一 | — | 以 GET /v1/models 返回为准 |
prompt | 必填 | string,非空 | — | 内容、构图、风格或编辑指令 |
resolution | 可选 | 1k / 2k | 1k | 像素档位,也是计费档位 |
quality | 可选 | low / medium / auto | auto | Grok 自己的参数 |
aspect_ratio | 可选 | 16 个取值,见画幅表 | auto(1:1) | 决定画面形状 |
n | 可选 | 整数 1–10 | 1 | 按实际返回张数计费 |
mask | 不支持 | — | — | 传了直接 400 |
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 | 必填 | 1–5 张(Quality 1–3 张),URL 或 Data URL | — | 超出被拒绝 |
image可以是 URL 字符串、字符串数组或{ "url": ... };也可以用 xAI 原生的images([{ "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 下的实测出图尺寸:
aspect_ratio | 实测出图(1k) | 比例 |
|---|---|---|
1:1 | 1024×1024 | 1.0000 |
16:9 | 1280×720 | 1.7778 |
9:16 | 720×1280 | 0.5625 |
4:3 | 1152×864 | 1.3333 |
3:4 | 864×1152 | 0.7500 |
3:2 | 1248×832 | 1.5000 |
2:3 | 832×1248 | 0.6667 |
2:1 | 1408×704 | 2.0000 |
1:2 | 704×1408 | 0.5000 |
21:9 | 1568×672 | 2.3333 |
19.5:9 | 1248×576 | 2.1667 |
5:2 | 1600×640 | 2.5000 |
auto / 省略 | 1024×1024 | 1.0000 |
9:19.5、20:9、9:20 同样是合法取值,上表未列它们的实测尺寸。resolution: 2k 保持同一形状、放大像素总量,例如 16:9 出 2816×1584、1:1 出 2048×2048。
返回结果
| 字段 | 类型 | 说明 |
|---|---|---|
data | array | 生成的图片,按实际张数返回 |
data[].url | string | 图片的临时下载链接 |
usage.cost_in_usd_ticks | integer | 官方计量值,按官方美元价计,单位为百亿分之一美元,原样保留;不是你的扣费 |
usage.cost | number | 本次扣费的人民币金额(已按分组倍率计算,与 usage.cost_usd 为同一笔扣费),最多 6 位小数 |
usage.cost_usd | number | 本次实际从余额扣除的美元金额,最多 8 位小数,与使用记录里这一条相同 |
usage.currency | string | usage.cost 的币种,恒为 CNY |
响应示例(URL 为占位符,其他 metadata 省略):
{
"data": [
{
"url": "https://example.com/generated-image.png"
}
],
"usage": {
"cost_in_usd_ticks": 200000000,
"cost": 0.0816,
"cost_usd": 0.012,
"currency": "CNY"
}
}同样的扣费也在响应头 X-HopBase-Cost、X-HopBase-Cost-USD 与 X-HopBase-Currency 里返回。生成耗时约 40 秒以上时,HopBase 会先发出 200 响应头再写保活空白,此时响应头里没有扣费,请以响应体的 usage.cost_usd(美元,与使用记录一致)或 usage.cost(人民币)对账。未扣费的失败不带这些字段。详见扣费说明。
收到后请立即下载保存。响应不带 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 是临时链接,收到后请立即下载保存。
- 编辑参考图上限按型号:
grok-imagine-image、grok-imagine-image-2.0最多 5 张,grok-imagine-image-quality最多 3 张;不适用于视频参考图。 - 生图与视频是两个分组,密钥还包含 Grok 视频分组才能调视频。视频见 Grok Imagine 视频。
multipart 编辑只保留 model、prompt、image、n、resolution、aspect_ratio、quality,其他表单字段会被丢弃。
xAI 官方编辑文档没有列明单张文件字节数或输入像素上限。不能用输出的 resolution 推导,也不能套用 GPT Image 的 25 MiB / 4 MiB 规则。
请使用合理压缩的图片,素材仍受官方规格检查。
常见报错
| 报错 | 改法 |
|---|---|
resolution must be 1k or 2k | 改成 1k 或 2k |
this model does not support the mask parameter | 删掉 mask |
<model> accepts at most N reference images per edit, got M; remove K and try again | 参考图减到 N 张以内(Quality 3 张,其余 5 张) |
prompt must not be empty | 填写非空的 prompt |
/v1/images/edits requires at least one reference image: send "image" ... or "images" ... | 用 image 或 images 传参考图(Quality 1–3 张,其余 1–5 张) |
image must be a data URL or an http(s) URL | 裸 base64 改成完整 Data URL |
image object is missing the url field | 对象写成 { "url": ... } |
image models do not support Chat Completions, please use the Images API | 改调 /v1/images/generations |
400,消息含 content-moderated | 改写提示词;这类拒绝不计费 |
n、quality、aspect_ratio 超出范围时由模型自行拒绝并返回其消息。图片请求失败时检查 HTTP 状态及 error。
计费
按出图张数 × resolution 档计费,与像素宽高无关;/v1/images/edits 的每张参考图另计一笔,内容审核拒绝不计费。grok-imagine-image 传 2k 也会出图,按 1k 档单价计。
响应里的 usage.cost_in_usd_ticks 是官方美元计量值,不是你的扣费;usage.cost_usd 才是本次从你余额实际扣除的金额(美元),usage.cost 是同一笔的人民币金额。不要把官方计量值当成扣费,对账以 usage.cost_usd 或控制台「使用记录」为准。各档单价见上表模型卡,你的实际单价以模型广场为准。