MoonNexAI API Docs

Appearance

Grok 视频 ​

MoonNexAI 当前对外开放两个 Grok 视频模型：

  • grok-video-1.5：适合单张参考图图生视频，当前接口行为要求提供 1 张图片参考。
  • grok-image-video：适合多参考图视频，最多 5 张参考图。

两个模型都使用统一的 OpenAI-compatible 视频任务接口。提交后先保存 id 或 task_id，再通过查询接口读取状态和结果。

方法与路径 ​

http
POST /v1/videos
GET /v1/videos/{task_id}
GET /v1/videos/{task_id}/content

请求头：

http
Authorization: Bearer <MOONNEXAI_API_KEY>
Content-Type: application/json

模型能力 ​

模型输入模式时长比例清晰度参考图
grok-video-1.5单图图生视频最高 15 秒16:9、9:16、1:1、4:3、3:4480P、720P必须 1 张，推荐 input_reference
grok-image-video多参考图视频最高 15 秒16:9、9:16、1:1、4:3、3:4720P、1080P最多 5 张，推荐 reference_image_urls 或 references[]

字段口径 ​

字段说明
model填写 grok-video-1.5 或 grok-image-video。
prompt视频描述，建议包含主体、动作、镜头、场景和风格。
seconds / duration视频时长。当前建议传字符串，例如 "15"；最高 15 秒。
aspect_ratio / ratio视频比例，例如 16:9、9:16、1:1、4:3、3:4。
size / resolution清晰度：grok-video-1.5 支持 480P / 720P，grok-image-video 支持 720P / 1080P。
input_reference单张参考图或首帧图输入，适合 grok-video-1.5。
reference_image_urls多参考图输入，适合 grok-image-video。
references[]MoonNexAI 标准素材数组；Grok 视频当前只接收图片参考，不接收视频或独立音频参考。
content[]兼容多媒体内容写法；图片条目建议显式填写 role=reference_image 或 role=first_frame。
callback_url可选。任务完成后接收 MoonNexAI 回调。

单图图生视频 ​

json
{
  "model": "grok-video-1.5",
  "prompt": "保留人物服装和场景一致性，加入轻微运镜和环境光变化。",
  "input_reference": "https://example.com/first-frame.jpg",
  "seconds": "15",
  "aspect_ratio": "9:16",
  "size": "720P"
}

多参考图视频 ​

grok-image-video 支持多张图片参考，最多 5 张。推荐使用公网 URL 或 MoonNexAI 托管 URL；如果你已经通过素材接口创建了可用于生成的图片素材，也可以在模型支持时传 Asset://asset_xxx。

json
{
  "model": "grok-image-video",
  "prompt": "综合多张参考图的角色特征和场景质感，输出一段稳定的镜头运动视频。",
  "reference_image_urls": [
    "https://example.com/ref-1.jpg",
    "https://example.com/ref-2.jpg",
    "https://example.com/ref-3.jpg"
  ],
  "seconds": "15",
  "aspect_ratio": "3:4",
  "size": "1080P"
}

使用 references[] 也可以：

json
{
  "model": "grok-image-video",
  "prompt": "让 @hero 站在 @scene 的环境中，保持主体外观稳定，镜头缓慢推进。",
  "seconds": "15",
  "aspect_ratio": "16:9",
  "size": "720P",
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/hero.png",
      "alias": "hero"
    },
    {
      "media_type": "image",
      "role": "style_reference",
      "url": "https://example.com/scene.png",
      "alias": "scene"
    }
  ]
}

使用 content[] 传参考图时，建议显式填写图片用途：

json
{
  "model": "grok-image-video",
  "prompt": "保持角色外观稳定，加入轻微动作和景深变化。",
  "seconds": "15",
  "aspect_ratio": "1:1",
  "size": "720P",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/ref-1.jpg"
      },
      "role": "reference_image"
    }
  ]
}

提交响应 ​

提交成功后先保存 id 或 task_id：

json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "grok-video-1.5",
  "status": "submitted",
  "progress": 0,
  "created_at": 1730000000
}

查询结果 ​

bash
curl https://moonnexai.com/v1/videos/task_xxx \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

客户端应先判断 status。只有 succeeded 时才读取视频 URL；如果是 failed，请读取 error：

json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": 100,
  "model": "grok-video-1.5",
  "size": "720P",
  "seconds": "15",
  "url": "https://example.com/result.mp4",
  "video_url": "https://example.com/result.mp4",
  "result_url": "https://example.com/result.mp4",
  "created_at": 1730000000,
  "completed_at": 1730000040
}

如果客户端只想下载视频内容，也可以在任务成功后请求。该兼容下载入口优先返回 302 跳转到 MoonNexAI 媒体 URL；客户端应开启重定向跟随。若托管媒体暂不可用，接口可能回退为代理视频流：

bash
curl -L https://moonnexai.com/v1/videos/task_xxx/content \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -o result.mp4

Grok Imagine 视频模型 ​

以下 Grok Imagine 视频模型仍作为兼容模型保留。不同模型的时长、尺寸和参考图字段不同，提交前请按表格选择字段：

模型当前字段口径说明
grok-imagine-1.0-videovideo_config.video_length、video_config.aspect_ratio、video_config.resolution、reference_imagesGrok Imagine 1.0 视频模型。
grok-imagine-video-preview、grok-imagine-video-1.5-previewseconds、size、resolution、reference_imagesGrok Imagine 1.5 preview 视频模型。
grok-imagine-1.5-video-super-720pinput_reference、sizeGrok Imagine 1.5 720p 单图视频模型。

接入注意 ​

  • grok-video-1.5 当前接口行为要求 1 张参考图；不要提交纯文本请求，多图请使用 grok-image-video。
  • grok-image-video 当前最多使用 5 张图片参考，不支持参考视频、尾帧和独立音频。
  • 不要把首帧、尾帧、视频参考和独立音频字段混在 Grok 视频请求里；如果需要复杂多素材视频，请优先查看 视频模型矩阵 选择其它模型。
  • 业务代码不要只读取一个结果字段；建议按 video_url、result_url、url 的顺序兼容读取。

相关页面 ​