Grok Video 3 API

基本信息

请求参数

图片 URL 必须是上游服务器可直接访问的公网 HTTPS 地址；duration 必须传数字。

文生视频

curl -X POST "https://www.niuflu.com/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video-3-t",
    "prompt": "一只橘猫在雨后的城市街道缓慢行走，电影感镜头",
    "mode": "text",
    "aspect_ratio": "16:9",
    "duration": 6,
    "resolution": "720p"
  }'

创建成功

{
  "id": "task_xxxxxxxxx",
  "task_id": "task_xxxxxxxxx",
  "object": "video_task",
  "model": "grok-video-3-t",
  "status": "processing",
  "progress": 10
}

必须保存创建响应中的初始 id，下文称为 local_task_id。没有 id 时才回退读取创建响应的 task_id。

图生视频

单图首帧 · mode: frame

{
  "model": "grok-video-3-t",
  "prompt": "人物轻轻转头，镜头缓慢推进，保持自然光影",
  "mode": "frame",
  "images_url": ["https://example.com/first-frame.jpg"],
  "aspect_ratio": "9:16",
  "duration": 10,
  "resolution": "720p"
}

概念参考 · mode: ref

{
  "model": "grok-video-3-t",
  "prompt": "使用参考图中的人物与服装，生成电影感街景镜头",
  "mode": "ref",
  "images_url": [
    "https://example.com/character.jpg",
    "https://example.com/clothes.jpg"
  ],
  "aspect_ratio": "16:9",
  "duration": 10,
  "resolution": "720p"
}

查询任务

每 5～10 秒查询一次创建响应中的初始 id：

curl "https://www.niuflu.com/v1/videos/task_xxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

处理中响应

{
  "id": "task_xxxxxxxxx",
  "status": "processing",
  "progress": 26,
  "completed": false,
  "failed": false
}

完成响应

{
  "id": "task_xxxxxxxxx",
  "status": "completed",
  "progress": 100,
  "completed": true,
  "failed": false,
  "video_url": "https://..."
}

下载视频

curl -L "https://www.niuflu.com/v1/videos/task_xxxxxxxxx/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o grok-video.mp4

下载时继续使用同一个 API Key。不要直接在普通浏览器地址栏打开该地址，因为地址栏请求不会自动附带 Bearer Key。

JavaScript 完整示例

const apiBase = 'https://www.niuflu.com/v1';
const apiKey = process.env.NIUFLU_API_KEY;

const headers = {
  Authorization: `Bearer ${apiKey}`,
  'Content-Type': 'application/json',
};

// 创建只执行一次；不要对这个 POST 做自动重试。
const createResponse = await fetch(`${apiBase}/videos`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    model: 'grok-video-3-t',
    prompt: '一只橘猫在雨后的城市街道缓慢行走，电影感镜头',
    mode: 'text',
    aspect_ratio: '16:9',
    duration: 6,
    resolution: '720p',
  }),
});

if (!createResponse.ok) {
  throw new Error(`create failed: ${createResponse.status} ${await createResponse.text()}`);
}

const created = await createResponse.json();
const localTaskId = created.id ?? created.task_id;
if (!localTaskId) throw new Error('create response has no task id');

let task;
for (;;) {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const queryResponse = await fetch(
    `${apiBase}/videos/${encodeURIComponent(localTaskId)}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );

  if (!queryResponse.ok) {
    throw new Error(`query failed: ${queryResponse.status} ${await queryResponse.text()}`);
  }

  task = await queryResponse.json();
  const status = String(task.status ?? '').toLowerCase();
  if (task.failed || ['failed', 'error', 'cancelled'].includes(status)) {
    throw new Error(task.error ?? task.message ?? 'video generation failed');
  }
  if (task.completed || ['succeeded', 'completed', 'success'].includes(status)) break;
}

// 使用初始本地 ID，不要改用查询响应中的 task_id。
const contentUrl = `${apiBase}/videos/${encodeURIComponent(localTaskId)}/content`;
console.log({ localTaskId, contentUrl, progress: task.progress });

常见错误

在线实测结果

• POST /v1/videos 返回 HTTP 200
• 模型 grok-video-3-t
• 状态从 processing 变为 completed
• 进度达到 100%
• 内容类型为 video/mp4
• MP4 文件头为有效 ftyp