Grok Imagine video
支持文生视频、首帧和参考图片；参考视频不支持，参考音频不支持，也不支持首尾帧配对。首帧与普通参考图片是两种不同语义，不能仅根据图片数量互相替代。
模型与规格
| 模型 | 输出时长 | 分辨率 | 参考图片模式 |
|---|---|---|---|
grok-imagine-video | 1–15 秒 | 480p / 720p | 当前最多 7 张，最多 10 秒 |
grok-imagine-video-1.5 | 1–15 秒 | 480p / 720p / 1080p | 当前最多 7 张，预设最长 15 秒 |
标准版和 1.5 的模式时长分别按当前能力预设执行。文档中的“≥7”表示已有样本支持至少 7 张，不是最少上传 7 张，也不是上游已公布硬上限；PopGo 当前参考图片模式允许 1–7 张。
字段与模式
| 字段 | 类型 | 规则 |
|---|---|---|
model | string | 必填，使用上表公开模型名 |
prompt | string | 必填；最长 4096 UTF-8 字节 |
seconds | integer | 整数；按当前模式取值，界面默认 8 秒 |
resolution | string | 按型号选择，界面默认 720p |
aspect_ratio | string | 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3；默认 16:9；首帧模式省略 |
input_reference | object | 恰好一张首帧，对象内使用 image_url |
reference_images | object[] | 普通主体/风格参考；对象数组，每项使用 image_url |
首帧将输入作为画面起点；参考图片用于主体、风格与一致性，即使只有一张也仍可选择参考图片模式。input_reference 与 reference_images 互斥，不能混用；不要发送顶层 image_url，错误字段可能被静默忽略，仍生成和计费却不采用图片。
素材来源、比例与提示词
服务文档描述公网 URL 和完整 Data URL，但也记录过任务创建成功后公网图片抓取失败。PopGo 当前 Grok 预设使用 Base64：本地上传图片可转换为完整 data:image/...;base64,...；公网图片在此策略下需要读取后编码，浏览器跨域限制可能阻止这一步。裸 Base64、本地路径或分享页都不能代替图片数据。
首帧模式不发送 aspect_ratio，输出由输入画面决定，并可能由服务裁剪或缩放；需要确定构图时先裁剪图片。参考图片模式仍可指定比例。未公开任意比例如何处理的完整保证，不应假定任何尺寸都能原样保留。
4096 是字节上限，不是字符数。文档样本中纯中文 1365 字为 4095 字节可接受，1366 字为 4098 字节失败；混合文字应计算 UTF-8 编码长度。缩短提示词比原样重试有效。
请求示例
下面分别是首帧和普通参考图片。示例中 YOUR_IMAGE_DATA_URL 替换成完整图片 Data URL；文生视频删除全部参考字段。
{
"model": "YOUR_MODEL",
"prompt": "A person turns naturally toward the camera",
"seconds": 5,
"resolution": "720p",
"input_reference": { "image_url": "YOUR_IMAGE_DATA_URL" }
}
{
"model": "YOUR_MODEL",
"prompt": "Keep the subject and visual style consistent",
"seconds": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
"reference_images": [{ "image_url": "YOUR_IMAGE_DATA_URL" }]
}
未知字段与输出音频
seed、watermark 等字段不能因 HTTP 200 就认为已生效；未公开或当前预设未开放的参数不应添加。generate_audio 只控制输出音轨，绝不是参考音频入口。不要用未知字段覆盖互斥规则或时长限制。
错误与处理
| 错误或现象 | 处理 |
|---|---|
| reference-to-video duration exceeds 10s | 标准版参考图片模式改为最多 10 秒，不能靠改字段名绕过 |
| Prompt length exceeds 4096 | 按 UTF-8 字节缩短提示词 |
| Duration must be between 1 and 15 seconds | 使用整数时长并遵循模式更严格的上限 |
| Cannot specify both image and reference_images | 首帧和参考图片字段保留一套 |
| grok_media_no_eligible_account | 暂无可用服务容量；使用有限退避，不要并发反复创建 |
| imagine:content-moderated | 修改违规内容；文档曾记录此类错误仍有非零用量，检查 PopGo 实际账单 |
| 成功但没有参考效果 | 检查实际发送字段、图片下载阶段和成片；任务 ID 不能证明图片被使用 |
任务创建返回后保存 id，按 queued / in_progress / completed / failed 轮询。先查原任务再考虑重试；超时不等于未创建。权限、余额和可用容量应分别排查。完整查询、下载、成本与退避流程见 视频任务流程。