Grok 视频

本文介绍通过 AruHub 调用 grok-imagine-video 与 grok-imagine-video-1.5。接口核对日期：2026-10-31。聊天与图片模型请看 Grok 聊天与图片。

Grok 视频使用异步视频接口。 客户端先创建任务，再查询本站任务 ID；完成后通过返回的地址下载视频。/chat/completions、/images/generations 不适用于本文的视频请求。

本页目录（点击展开）

1. 客户端应该怎么填
2. 参数和能力边界
3. 文生视频请求
4. 单图参考请求
5. 轮询任务状态
6. 鉴权下载与网页播放
7. 错误与恢复
8. 交给 AI 的配置指令

1. 客户端应该怎么填

项目	填写内容
API 根地址	`https://api.aruhub.com`
仅追加 `/videos` 的 SDK Base URL	`https://api.aruhub.com/v1`
完整创建接口	`POST https://api.aruhub.com/v1/videos`
完整查询接口	`GET https://api.aruhub.com/v1/videos/{task_id}`
模型	`grok-imagine-video` 或 `grok-imagine-video-1.5`，以密钥可用列表为准
密钥	自己的 AruHub API Key
鉴权	`Authorization: Bearer YOUR_API_KEY`
请求体	JSON，`Content-Type: application/json`

密钥需要有目标模型权限。先用 GET /v1/models 查询 data[].id，不要把聊天模型、图片模型或简称 grok 填进视频请求。

AruHub 入口与 xAI 原生入口不同

本教程客户端使用 /v1/videos 创建任务。不要把 xAI 原生的 /v1/videos/generations 直接套到 AruHub 地址上。 AruHub 的另一套兼容入口是单数的 /v1/video/generations，它有不同的查询包装结构。详细区别见两套协议对照。

Studio 配置

打开 AruHub Studio，在设置的视频模型配置中新增模型。
协议选 New API，Base URL 填 https://api.aruhub.com，填入自己的 AruHub 密钥。
获取并选择 grok-imagine-video 或 grok-imagine-video-1.5，保存。
进入视频工作台，先用 6 秒、480p、16:9、纯文本 验证；等待完成后预览、下载。

这里选择 New API 是为了使用 AruHub 的兼容任务接口。Studio 中的 xAI Videos 模板面向原生 xAI 协议，不应仅替换为 AruHub 域名就直接使用。通用面板显示的时长、素材数量或分辨率也不等于 Grok 全部支持。

2. 参数和能力边界

参数	类型	说明
`model`	string，必填	`grok-imagine-video` / `grok-imagine-video-1.5`
`prompt`	string，必填	非空提示词
`duration`	integer，必填	1～15 秒的整数；推荐首次用 `6`
`resolution`	string，建议必填	首次用 `480p`；常规可选 `720p`；不要默认所有模型与输入模式都支持 1080p
`aspect_ratio`	string，建议必填	首次用 `16:9`，竖屏用 `9:16`；常用值还包括 `1:1`、`4:3`、`3:4`、`3:2`、`2:3`
`image`	object，可选	单张参考图，格式为 `{"url":"公网图片直链"}`
`n`	integer，可省略	仅接受 `1`，每个请求创建一个视频任务

Seedance 使用 ratio，Grok 推荐使用 aspect_ratio。 不要把两种模型的字段直接混用。duration 必须明确给出，不依赖上游默认时长。

兼容字段包括 seconds / duration_seconds、size 和部分 metadata 字段，但新代码只使用上表中的顶层参数。多个时长、分辨率字段同时出现时必须一致；不一致会返回 conflicting ... fields。

关于 1080p、图生视频和高级功能

当前适配层接受 480p、720p、1080p 字段值；上游能否执行，还取决于具体模型、输入模式和当前服务能力。不要把“参数校验通过”当成生成成功。
已有生产成功记录包含 grok-imagine-video 的 6 秒 480p 文生视频，以及 grok-imagine-video-1.5 的 6 秒 720p 文生视频。本文没有额外验证所有分辨率、比例与素材组合。
当前单图 JSON 请求已具备字段转换支持；本次未做真实图生视频验收。建议在文生视频跑通后，单独验证图片场景。
当前 Grok 接入不支持 multipart 文件上传、多图、参考视频、参考音频、remix、续写、视频编辑、首尾帧或关键帧接口。没有完成 webhook。
不要发送 parameters、width、height，这些字段在当前适配器中明确被拒绝。也不要照搬 Seedance 的 videos、audios、mode 等字段；没有明确支持的字段不能假设会生效。

3. 文生视频请求

以下为 Bash 命令；先设置 ARUHUB_API_KEY。Windows 用户使用 PowerShell 版本。

bash

curl --fail-with-body --max-time 180 \
  https://api.aruhub.com/v1/videos \
  -H "Authorization: Bearer $ARUHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "grok-imagine-video",
    "prompt": "A small red ball rests on a wooden table. Static camera, gentle daylight, subtle natural movement.",
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }'

提示词也可以使用中文。若选择 1.5，修改 model 为 grok-imagine-video-1.5，其余异步处理流程相同；不要因模型名变了而改用另一套端点。

创建响应示意：

json

{
  "id": "YOUR_LOCAL_TASK_ID",
  "task_id": "YOUR_LOCAL_TASK_ID",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued"
}

立即持久保存顶层 id。本教程返回的是 AruHub 本地任务 ID，不是 xAI 原生的 request_id。不要等待创建响应中的 video.url，也不要根据 xAI 示例改成轮询上游任务 ID。

4. 单图参考请求

先把图片放到生成服务可读取的公网地址，再添加 image：

json

{
  "model": "grok-imagine-video",
  "prompt": "保持参考图主体外观，主体自然轻微运动，镜头缓慢推近。",
  "duration": 6,
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "image": {"url": "https://YOUR_PUBLIC_MEDIA_HOST/reference.jpg"}
}

占位地址必须替换为真实图片直链。当前文档推荐公网 HTTPS 图片 URL，不把裸 Base64、Data URI、本地路径或 multipart 当作已验证的 Grok 上传方式。需要从电脑选图时，先由你自己的后端 / 对象存储上传，得到可访问 URL，再提交上述 JSON。

兼容层还可读取 input_reference 或单元素 images 数组，但不要同时发送多种字段；多张图片或互相冲突的图片引用会被拒绝。

5. 轮询任务状态

bash

curl --fail-with-body \
  "https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID" \
  -H "Authorization: Bearer $ARUHUB_API_KEY"

每 5 秒查询一次，后续可增加到 10～15 秒。queued / in_progress 继续等待，failed 读取 error.message，completed 才开始取片。progress 只是进度信息，不应替代 status 判断完成。

完成响应示意：

json

{
  "id": "YOUR_LOCAL_TASK_ID",
  "task_id": "YOUR_LOCAL_TASK_ID",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "/v1/videos/YOUR_LOCAL_TASK_ID/content"
  }
}

当前 Grok 的成片地址可能只在 metadata.url，顶层 video_url 可以不存在。 通用客户端使用 video_url || metadata.url，并允许结果是以 / 开头的相对路径。

相对路径必须相对于 API 根域名解析。例如：

text

返回：/v1/videos/YOUR_LOCAL_TASK_ID/content
实际下载：https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID/content

不要解析到 docs.aruhub.com、你自己的网站域名或 studio.aruhub.com。JavaScript 可使用 new URL(resultUrl, "https://api.aruhub.com")。

6. 鉴权下载与网页播放

下载本站 /v1/videos/{id}/content 时，使用自己的 AruHub API Key：

bash

curl --fail-with-body --max-time 300 \
  "https://api.aruhub.com/v1/videos/YOUR_LOCAL_TASK_ID/content" \
  -H "Authorization: Bearer $ARUHUB_API_KEY" \
  --output grok-result.mp4

这是二进制响应，不是 JSON。通常是 video/mp4；内容接口可能返回 HTTP 200 或 206，206 是分段传输状态，不能直接判为生成失败。自建下载器应核对 Content-Range 与实际字节数，避免把不完整分段当作完整文件保存。

为什么浏览器直接打开链接会失败

<video src="..."> 和普通地址栏访问通常不会自动携带 Authorization: Bearer ...。因此任务已完成，仍可能出现播放器 401 / 403 或空白。

自建网站推荐采用下面的结构：

前端只把生成参数和你网站自己的用户身份传给后端。
后端持有 AruHub 密钥，创建、轮询并保存任务归属。
完成后，后端鉴权读取本站 content 接口，把视频保存到你的对象存储，或通过你自己的受保护接口流式转发。
前端播放器使用你网站自己的视频地址或短时授权地址。需要拖动进度时，后端正确转发 Range / Content-Range。

个人本地工具也可在自己的运行环境中鉴权下载，再生成本地 Blob URL 播放。不要把公共网站后端的共享密钥打包到前端代码，也不要把密钥拼成 ?api_key=... 放进下载地址。

视频 URL 若指向外部托管域名，下载时不要转发 AruHub 密钥。只向 https://api.aruhub.com 的本站接口发送该密钥，下载重定向到外部域名时同样需要移除鉴权头。

7. 错误与恢复

现象 / 报错	应对方式
`/v1/videos/generations` 返回 404	使用 AruHub 的 `/v1/videos`；不要混入原生 xAI 创建路径
`xAI video requires an application/json request`	发送 JSON；不要上传 multipart 文件
`duration or seconds is required`	明确填写顶层 `duration`，范围 1～15 秒
`conflicting duration/resolution fields`	清理客户端自动附加的 `seconds`、`size`、`metadata` 等冲突项
`xAI video does not accept parameters/width/height`	删除对应字段，改用顶层 `duration`、`resolution`、`aspect_ratio`
`xAI video accepts a single input image`	只保留一张参考图，不发送多图数组
completed 但 `video_url` 为空	读取 `metadata.url`，这是当前 Grok 正常返回方式
下载地址以 `/v1/...` 开头	相对于 `https://api.aruhub.com` 解析
content 接口 401 / 403	检查是否发送自己的 AruHub Bearer 密钥，任务是否属于该身份
content 接口 206	按视频分段响应处理，检查范围；不要当作生成失败
轮询时临时 429 / 5xx	延迟后继续 GET 原任务；不要 POST 新任务
审核或生成失败	读取错误原因，停止该任务轮询，修改内容后由用户决定是否重新提交
`invalid api platform: 48`	保留任务时间、模型和脱敏报错联系支持，不通过乱改协议或模型名反复重试
页面刷新后丢了视频任务	客户端应持久化本地任务 ID，恢复时继续查询，不重新创建

8. 交给 AI 的配置指令

text

请为我的软件接入 AruHub Grok 视频，先阅读：
https://docs.aruhub.com/guide/grok-video
https://docs.aruhub.com/guide/video-api

API根地址：https://api.aruhub.com。
模型使用 grok-imagine-video 或 grok-imagine-video-1.5，以 ARUHUB_API_KEY 可见的模型为准。
密钥从环境变量读取，不写进源码或公开前端。
新代码 POST /v1/videos 创建，GET /v1/videos/{创建返回的本地id} 查询。
不要使用原生xAI的 /v1/videos/generations，不使用聊天或图片接口。
最小JSON：model、prompt、duration:6、resolution:"480p"、aspect_ratio:"16:9"。
时长1～15秒整数；先验证480p，再尝试目标模型支持的其他组合。
仅单图参考：image:{"url":"公网图片直链"}；不使用multipart、多图、参考音视频、remix或编辑。
创建后立即持久保存顶层id；每5秒GET查询，适当退避。
queued/in_progress继续等待；failed显示error.message；completed读取video_url或metadata.url。
Grok可能只返回metadata.url，且值为 /v1/videos/{id}/content。
相对路径解析到API根域名；本站content下载携带自己的AruHub密钥。
外部视频URL和跨域重定向不得收到AruHub密钥。不要将密钥放进URL查询参数。
content是二进制视频，200/206都需正确处理；检查完整性后保存文件。
网页播放器通过自己的后端鉴权代理或保存后的媒体地址播放，不能假设video标签会带Bearer头。
没有完成webhook；GET临时失败可退避重试，POST创建超时不自动重发。
先做配置和无生成验证，展示实际请求地址与脱敏JSON；用户确认试运行后提交一次最小任务。
交付配置文件位置、启动命令、任务ID保存/恢复方式、视频下载位置和异常处理。

下载 AI 可读的完整接入说明 · 可运行 Python / Node.js 示例 · Seedance 2.5 视频

Grok 视频 ​

1. 客户端应该怎么填 ​

Studio 配置 ​

2. 参数和能力边界 ​

关于 1080p、图生视频和高级功能 ​

3. 文生视频请求 ​

4. 单图参考请求 ​

5. 轮询任务状态 ​

6. 鉴权下载与网页播放 ​

为什么浏览器直接打开链接会失败 ​

7. 错误与恢复 ​

8. 交给 AI 的配置指令 ​

Grok 视频

1. 客户端应该怎么填

Studio 配置

2. 参数和能力边界

关于 1080p、图生视频和高级功能

3. 文生视频请求

4. 单图参考请求

5. 轮询任务状态

6. 鉴权下载与网页播放

为什么浏览器直接打开链接会失败

7. 错误与恢复

8. 交给 AI 的配置指令