主题
Grok 生图与生视频
路梦云图 的 Grok 分组提供 xAI Imagine 系列的图片与视频生成能力：文生图、图生图、文生视频、图生视频。图片走 OpenAI 兼容格式同步返回，视频是异步任务，需要提交后轮询再下载。
前置条件
本页接口仅对 Grok 平台分组的 Key 生效。Key 分组不匹配时会返回 404，提示模型不存在或无访问权限。生图生视频还需要分组开启对应权限（由管理员配置）。
Grok 的图片接口与 图片生成 API 中的 OpenAI / Gemini 格式参数不通用。Grok 上游不认 size（1024x1024 这类像素尺寸），请用 aspect_ratio + resolution 控制画面，详见 与通用图片接口的差异。
接口一览
| 用途 | 方法与路径 | 同步 / 异步 |
|---|---|---|
| 文生图 | POST https://xmlumen.org/v1/images/generations | 同步 |
| 图生图（编辑） | POST https://xmlumen.org/v1/images/edits | 同步 |
| 提交视频任务 | POST https://xmlumen.org/v1/videos/generations | 异步，返回 request_id |
| 查询任务状态 | GET https://xmlumen.org/v1/videos/{request_id} | — |
| 下载视频内容 | GET https://xmlumen.org/v1/videos/{request_id}/content | — |
认证统一使用 Authorization: Bearer YOUR_API_KEY。
可用模型
先用模型列表确认当前 Key 实际开放的模型：
bash
curl https://xmlumen.org/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"图片与视频相关的模型如下：
| 模型 | 用途 | 计费（标准价） |
|---|---|---|
grok-imagine-image | 文生图 / 图生图 | $0.02 / 张（1k / 2k 同价） |
grok-imagine-image-2.0 | 文生图 / 图生图，xAI 当前主推的图片模型 | 1k $0.06 / 张；2k $0.08 / 张 |
grok-imagine-image-quality | 文生图 / 图生图，高质量（上游已退役，见下方说明） | 1k $0.05 / 张；2k $0.07 / 张 |
grok-imagine | 仅图片端点可用，网关映射成 grok-imagine-image-quality | 按 quality 计价 |
grok-imagine-video | 文生视频 / 图生视频，最高 720p | 480p $0.05 / 秒；720p $0.07 / 秒 |
grok-imagine-video-1.5 | 文生视频 / 图生视频，支持 1080p | 见 计费规则 |
模型列表里有几项容易踩坑
grok-imagine-image-quality：xAI 已于 2026-11-02 退役该型号，旧名请求由grok-imagine-image-2.0（quality: low）承接，平台仍按上表 quality 单价计费。新接入建议直接用grok-imagine-image-2.0或grok-imagine-image。grok-imagine-edit：旧别名，部分账号下会返回404 does not exist or your team does not have access。图生图请直接用grok-imagine-image或grok-imagine-image-2.0。grok-imagine：视频接口返回404，不要用来生视频。图片接口可用，网关会映射成grok-imagine-image-quality并按后者计费。grok-imagine-video-1.5：现已原生支持文生视频，不带参考图也按 1.5 单价计费；只需要普通画质的视频时，用更便宜的grok-imagine-video。
以上以你的分组实际配置为准，接入前建议先用一次小请求验证。
生成图片
文生图
bash
curl https://xmlumen.org/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "一只小熊猫在笔记本电脑前敲代码，电影感光线",
"aspect_ratio": "16:9",
"resolution": "1k",
"n": 1,
"response_format": "url"
}'响应：
json
{
"data": [
{
"url": "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-xxxx.jpeg",
"mime_type": "image/jpeg"
}
],
"usage": { "cost_in_usd_ticks": 200000000 }
}国内网络建议使用 b64_json
response_format: "url" 返回的是 xAI 自有 CDN（imgen.x.ai）的直链，不经过 路梦云图 网关，国内网络环境下经常连不通。
需要稳定拿到图片时请使用 response_format: "b64_json"，图片数据会随响应体经网关一并返回：
bash
curl https://xmlumen.org/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "一只小熊猫在笔记本电脑前敲代码，电影感光线",
"aspect_ratio": "1:1",
"resolution": "1k",
"response_format": "b64_json"
}'一次生成多张图片使用 n，按张数线性计费（n: 4 即 4 倍单价）：
bash
-d '{ "model": "grok-imagine-image", "prompt": "…", "n": 4 }'图生图（编辑）
参考图请用 JSON，填公网可访问的地址。字段是嵌套对象 image.url，不要写成顶层 image_url：
bash
curl https://xmlumen.org/v1/images/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "改成赛博朋克霓虹夜景风格，保持主体不变",
"aspect_ratio": "9:16",
"resolution": "1k",
"response_format": "b64_json",
"image": { "url": "https://example.com/input.jpg" }
}'需要多张参考图时改用 images 数组（如 "images": [{ "url": "https://..." }, { "url": "https://..." }]），不要和 image 同时传；网关单次最多接受 3 张。
不要用 multipart 上传本地文件
/v1/images/edits 若用 multipart/form-data 上传本地文件（-F image=@input.jpg），网关可能把文件转成 data URL 再交给上游，xAI 会返回 400 Invalid base64-encoded image。
请先把图片放到可公网访问的地址（对象存储、图床等），再通过 image.url 传入。
图片请求参数
| 参数 | 必填 | 说明 |
|---|---|---|
model | 是 | grok-imagine-image、grok-imagine-image-2.0 或 grok-imagine-image-quality；grok-imagine 在图片端点可用，会映射成 quality |
prompt | 是 | 图片描述，不能为空 |
n | 否 | 生成张数，默认 1；按张数线性计费 |
aspect_ratio | 否 | 画面宽高比，见下方合法取值。不填时由模型自行决定 |
resolution | 否 | 图片清晰度档，只有 1k / 2k 两档（写成大写会被网关转为小写），不填默认 1k。1k 输出长边约 1024，2k 约 2048 |
quality | 否 | 仅 grok-imagine-image-2.0 支持：low / medium / auto，默认 auto |
response_format | 否 | url 返回 xAI CDN 直链；b64_json 返回 base64（国内推荐） |
image | 图生图必填 | 嵌套对象 {"url": "https://..."}，须公网可访问。不要写成顶层 image_url；多张参考图改用 images 数组，最多 3 张 |
aspect_ratio 合法取值：
| 取值 | 说明 |
|---|---|
1:1 | 方图 |
16:9 / 9:16 | 横屏 / 竖屏 |
4:3 / 3:4 | 传统横图 / 竖图 |
3:2 / 2:3 | 摄影比例 |
2:1 / 1:2 | 超宽 / 超高 |
19.5:9 / 9:19.5 | 全面屏手机比例 |
20:9 / 9:20 | 更长的全面屏比例 |
21:9 / 5:2 | 超宽横幅 |
auto | 由模型按提示词推断，是上游合法取值，不是占位符 |
用 aspect_ratio + resolution 控制画面，size 只会被换算
Grok 上游不认 size。网关转发前会删掉 size；如果请求里没写 aspect_ratio / resolution，会先按 size 换算：长边 ≤1024 记 1k、否则记 2k，比例取最接近的合法值。换算结果未必是你想要的，请直接写明这两个字段：
aspect_ratio：比例（上表 16 档）resolution：1k或2k
输出不是固定 1024×1024，也没有 4K 档；图片生成 API 里的尺寸写法不适用于 Grok 分组。计费档位的判断方式见 计费规则。
生成视频
视频生成是异步的，完整流程分三步：提交任务 → 轮询状态 → 下载内容。
第一步：提交任务
bash
curl https://xmlumen.org/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video",
"prompt": "海浪在日落时分拍打礁石，航拍镜头",
"resolution": "720p",
"duration": 8,
"aspect_ratio": "16:9"
}'立即返回任务 ID（通常 1 秒内）：
json
{ "request_id": "892b47b9-155b-97e3-b386-ae0ba3cee9ed" }第二步：轮询状态
bash
curl https://xmlumen.org/v1/videos/892b47b9-155b-97e3-b386-ae0ba3cee9ed \
-H "Authorization: Bearer YOUR_API_KEY"生成中返回 202，带进度百分比：
json
{ "status": "pending", "progress": 87 }完成后返回 200：
json
{
"model": "grok-imagine-video",
"status": "done",
"progress": 100,
"usage": { "cost_in_usd_ticks": 5600000000 },
"video": {
"duration": 8,
"respect_moderation": true,
"url": "/v1/videos/892b47b9-155b-97e3-b386-ae0ba3cee9ed/content"
}
}建议轮询间隔 5 秒，8 秒的视频通常 30 秒内完成。
第三步：下载视频
video.url 是相对路径，需要拼接 Base URL，并且必须携带认证头（无 Key 访问返回 401）：
bash
curl -L -o output.mp4 \
https://xmlumen.org/v1/videos/892b47b9-155b-97e3-b386-ae0ba3cee9ed/content \
-H "Authorization: Bearer YOUR_API_KEY"返回 Content-Type: video/mp4（H.264 编码）。视频经由 路梦云图 网关回源，国内网络可直接下载，无需代理。
图生视频
参考图必须是公网 URL，请求体用 JSON。有两种用法：
- 单图生视频：
image: { "url": "..." }，这张图作为视频首帧，产物比例跟随参考图； - 多图参考生视频：
reference_images: [{ "url": "..." }, ...]，多张图共同影响人物 / 物体 / 风格，最高 720p。
| 模型 | reference_images 上限 | 多图参考时长上限 | image 与 reference_images 同时传 |
|---|---|---|---|
grok-imagine-video | 7 张 | 10 秒 | 不允许，返回 400 |
grok-imagine-video-1.5 | 14 张 | 15 秒 | 允许，image 作为首帧 |
两种用法都不要写顶层 image_url，也不要用已废弃的 images。
单张参考图（产物第一帧贴近这张图）：
bash
curl https://xmlumen.org/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5",
"prompt": "画面中的苹果缓慢旋转",
"resolution": "720p",
"duration": 8,
"image": { "url": "https://example.com/apple.jpg" }
}'多张参考图（reference-to-video，最高 720p）：
bash
curl https://xmlumen.org/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5",
"prompt": "两个人物在雨夜街道并肩走过，电影感",
"resolution": "720p",
"duration": 8,
"reference_images": [
{ "url": "https://example.com/person-a.jpg" },
{ "url": "https://example.com/person-b.jpg" },
{ "url": "https://example.com/street.jpg" }
]
}'后续轮询与下载步骤与文生视频完全一致。
参考图字段写错会白花钱，或直接 400
- 写成顶层
"image_url": "..."：上游静默丢弃该字段，返回200、request_id照发、费用照扣，结果却与参考图无关（退化成文生视频），没有任何报错。 grok-imagine-video同时传image和reference_images：400 Cannot specify both 'image' and 'reference_images'...（grok-imagine-video-1.5允许同时传）。- 用已废弃的
images：400 The images field is deprecated. Please use reference_images instead. - 用
multipart/form-data上传本地文件：415。
json
// ❌ 静默丢弃，白花钱
{ "image_url": "https://example.com/apple.jpg" }
// ❌ 已废弃
{ "images": [{ "url": "https://a.jpg" }] }
// ✅ 单图生视频
{ "image": { "url": "https://example.com/apple.jpg" } }
// ✅ 多图参考生视频
{ "reference_images": [{ "url": "https://a.jpg" }, { "url": "https://b.jpg" }] }
// ✅ 仅 grok-imagine-video-1.5：首帧 + 多图参考
{ "image": { "url": "https://a.jpg" }, "reference_images": [{ "url": "https://b.jpg" }] }不支持上传本地图片文件
视频接口不支持 multipart/form-data。请先把图片上传到可公网访问的地址，再按张数选择 image 或 reference_images。
单张参考图时，产物宽高比跟随参考图
单张 image 生效时，产物的宽高比会跟随参考图，而不是 resolution 隐含的 16:9。例如传入 1:1 的方图，480p 档实际输出 544×544 而不是 848×480。多张 reference_images 时可用 aspect_ratio 指定比例。
视频请求参数
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
model | 是 | — | grok-imagine-video 或 grok-imagine-video-1.5 |
prompt | 是 | — | 视频描述，不能为空 |
resolution | 否 | 480p | 480p（848×480）/ 720p（1280×720）/ 1080p。grok-imagine-video 最高 720p；1080p 仅 grok-imagine-video-1.5 的文生视频与单图生视频可用 |
duration | 否 | 8 | 视频时长（秒），取值范围 1–15；grok-imagine-video 多图参考时最长 10 秒 |
aspect_ratio | 否 | 16:9 | 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 5:2（与图片的取值不同）。单图生视频时被忽略，产物比例跟随参考图 |
image | 否 | — | 首帧参考图，形如 {"url": "https://..."}，须公网可访问 |
reference_images | 否 | — | 多图参考，形如 [{"url":"..."}, ...]：grok-imagine-video 最多 7 张，grok-imagine-video-1.5 最多 14 张。不要用已废弃的 images |
1080p 只有 1.5 支持
grok-imagine-video 传 resolution: "1080p" 会返回 400 1080p video resolution is not available for this model.
grok-imagine-video-1.5 的文生视频与单图生视频支持 1080p（$0.25 / 秒）；多图参考（reference_images）最高 720p。
其它非法取值（如 360p）会返回 422。
计费规则
以下价格为平台标准价，实际扣费还要乘以你所在分组的倍率，请以控制台 用量统计 为准。
图片：按张数 × 清晰度档计费
| 模型 | 1k 档 | 2k 档 |
|---|---|---|
grok-imagine-image | $0.02 / 张 | $0.02 / 张 |
grok-imagine-image-2.0 | $0.06 / 张 | $0.08 / 张 |
grok-imagine-image-quality | $0.05 / 张 | $0.07 / 张 |
n 张即 n 倍价格，与 quality 参数无关。grok-imagine 走图片端点时按 grok-imagine-image-quality 计价。
计费档位按 size 判断
目前平台按请求里的 size 判断图片计费档位（长边 ≤1024 记 1k，否则记 2k），没传 size 时一律按 2k 档计价，即使 resolution 填的是 1k。grok-imagine-image 两档同价，不受影响；用 grok-imagine-image-2.0 / grok-imagine-image-quality 出 1k 图时，可以在写明 aspect_ratio 与 resolution 的同时带上 "size": "1024x1024"。这种情况下 size 只用来判断计费档位，转发前会被删掉。
视频：按模型 × 分辨率 × 秒数计费
| 模型 | 480p | 720p | 1080p | 8 秒示例 | 15 秒上限 |
|---|---|---|---|---|---|
grok-imagine-video | $0.05 / 秒 | $0.07 / 秒 | 不可用 | 720p = $0.56 | 720p = $1.05 |
grok-imagine-video-1.5 | $0.08 / 秒 | $0.14 / 秒 | $0.25 / 秒 | 720p = $1.12；1080p = $2.00 | 720p = $2.10；1080p = $3.75 |
grok-imagine-video-1.5 的文生视频与图生视频同价，都按上表 1.5 单价计费。
视频提交即扣费，生成失败不退款
视频费用在任务提交成功的那一刻就已计入，而不是等视频真正产出。
这意味着：如果生成结果被上游内容审核拒绝（轮询时返回 400 Generated video rejected by content moderation.），这笔费用依然会被扣除且不会自动退还。
视频单价远高于图片（一个 grok-imagine-video 的 720p / 15 秒 = $1.05 ≈ 52 张标准图），提交前请确认提示词符合内容规范，避免无谓损耗。
参数校验失败（400）不会产生费用，可放心用于调试。字段写错但请求仍被当成文生视频（顶层 image_url）会扣费。
与通用图片接口的差异
如果你已经在用 图片生成 API，接入 Grok 时注意这些区别：
| 维度 | OpenAI / Gemini 分组 | Grok 分组 |
|---|---|---|
| 尺寸参数 | size 填真实宽高，决定计费档位 | 用 aspect_ratio + resolution（1k / 2k）控制画面；size 会被网关换算后删除，只影响计费档位 |
| 清晰度档位 | 按最长边分 1K / 2K / 4K | 图片只有 1k / 2k；视频是 480p / 720p / 1080p |
| 计费方式 | 按清晰度档位 | 图片：张数 × 模型 × 档位单价；视频：模型 × 分辨率 × 秒数 |
| 图生图参考图 | multipart 上传文件 | JSON 的公网 image.url（多图用 images，最多 3 张）；multipart 容易 400 Invalid base64 |
| 图片 URL | 网关代理返回 | xAI CDN 直链，国内需用 b64_json |
| 视频生成 | 不支持 | 支持，异步三段式 |
错误处理
| 状态码 / 错误 | 原因与处理 |
|---|---|
400 Prompt cannot be empty | prompt 为空，填写有实际画面含义的描述 |
400 model is required | 请求体缺少 model 字段 |
400 Invalid base64-encoded image | 图生图用 multipart 上传了本地文件，网关转成 data URL 后上游不认。改用公网 URL 的 JSON image.url |
400 Duration must be between 1 and 15 seconds | duration 超出 1–15 秒范围 |
400 1080p video resolution is not available | grok-imagine-video 不支持 1080p，请用 480p / 720p，或改用 grok-imagine-video-1.5（多图参考除外） |
400 Cannot specify both 'image' and 'reference_images' | grok-imagine-video 不能同时传这两个字段：单图用 image，多图用 reference_images；需要「首帧 + 多图参考」请改用 grok-imagine-video-1.5 |
400 The images field is deprecated | 视频不要传 images，多张参考图改用 reference_images |
400 Generated video rejected by content moderation | 生成结果被上游内容审核拒绝，费用不退，请调整提示词 |
401 authentication_error | Key 无效或缺少认证头；下载视频内容时也必须带 Authorization |
404 The model xxx does not exist… | 模型名不可用（如 grok-imagine-edit，或把 grok-imagine 拿去生视频），换用 可用模型 中列出的名称 |
404 Video request not found | request_id 不存在，或不属于当前 Key |
415 upstream_error | 视频接口用 multipart 上传了图片文件，请改用 JSON 的公网 URL |
422 upstream_error | 参数取值上游不接受，如 resolution 填了 360p |
429 | 触发速率限制或上游繁忙，稍后重试 |
| 无报错，但参考图不生效 | 参考图写成了顶层 image_url。上游静默丢弃未知字段，返回 200 且照常扣费，结果却是文生视频。按张数改用 image 或 reference_images，见 图生视频 |
注意事项
- 图片同步、视频异步：图片请求约 5–10 秒返回，客户端超时建议 ≥ 60 秒；视频提交是秒回，真正的等待发生在轮询阶段。
- 视频必须带 Key 下载：
/content端点有鉴权，不能直接把链接贴到浏览器或分享给他人。 - 图片 URL 有有效期：xAI CDN 直链会过期，需要长期保存请及时下载，或直接用
b64_json。 - 参考图必须公网可达：图生图、图生视频都不接受本地文件直传；先上传到对象存储或图床。
- 按需选视频模型：
grok-imagine-video-1.5文生视频、图生视频都按 1.5 单价计费，要 1080p 才需要它；普通画质的视频用grok-imagine-video更省。 - 提示词写具体：覆盖主体、动作、风格、构图、光线；视频还应描述镜头运动（航拍、推近、慢镜头等），描述越具体结果越稳定。
- 实际可用模型、分辨率与价格以你的分组和后台配置为准，接入前建议先跑一次小额验证。