视频生成请求文档

Developer Docs / Video Generation

通过公网 API 创建视频生成任务、查询状态并获取视频地址

视频生成是异步任务。创建接口会返回 task_id 或 id，客户端需要保存该 ID，并持续查询任务状态，直到成功返回 data.video_url / result_url，或失败返回 fail_reason。

Base URL https://img.apixgo.com

模型列表 GET /v1/models

创建任务 POST /v1/video/generations

查询任务 GET /v1/video/generations/{task_id}

接口概览

本 API 用于提交文生视频、单参考图生视频、多参考图生视频请求。推荐调用方先通过 /v1/models 动态读取可用模型，再根据模型能力构造请求。

默认推荐模型为 grok-imagine-video。如果使用 grok-imagine-video-1.5-preview，必须提供且只能提供 1 张参考图。

中转站接入提醒

测试连通性时，建议使用真实请求地址、站内 Key 和映射后的模型名进行端到端测试。不要只依赖 newapi/sub2api 的测试按钮判断可用性。

请求流程

读取模型
调用 GET /v1/models 获取当前可用模型，避免把模型列表写死。
创建任务
调用 POST /v1/video/generations，提交提示词、秒数、画幅和参考图。
保存任务 ID
使用 response.task_id || response.id 作为后续查询 ID。
轮询结果
每 5 秒查询一次，成功后优先下载 data.data.video_url 对应的视频文件。

认证方式

所有接口使用 Bearer Token。请在用户控制台创建或复制 API Key，并放入请求头。

HTTP Header

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

不要把 API Key 写入前端网页、移动端安装包或公开仓库。生产环境建议由自己的后端服务代为调用。

模型能力

查询可用模型

curl -X GET "https://img.apixgo.com/v1/models" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

`grok-imagine-video`

通用默认模型。
文生视频最长 15 秒。
单参考图生视频最长 15 秒。
多参考图生视频最长 10 秒。
最多支持 7 张参考图。

`grok-imagine-video-1.5-preview`

单图生视频预览模型。
不支持纯文生视频。
必须提供且只能提供 1 张参考图。
最长支持 15 秒。
画幅建议使用 16:9 或 9:16。

请求参数

字段	类型	必填	说明
`model`	string	是	模型 ID：`grok-imagine-video` 或 `grok-imagine-video-1.5-preview`。
`prompt`	string	是	视频提示词，不能为空。
`seconds`	string	否	视频秒数，范围 `1`–`15`，例如 `"6"`。多参考图最长 10 秒。
`size`	string	否	兼容尺寸：`1280x720`、`720x1280`、`1792x1024`、`1024x1792`。
`aspect_ratio`	string	否	画幅比例，默认建议 `16:9`。
`resolution`	string	否	清晰度，建议 `720p` 或 `480p`。
`image`	string	否	单张参考图 URL。1.5 Preview 必须使用此字段且只能传 1 张。
`reference_images`	array<string>	否	多参考图 URL 数组，仅用于 `grok-imagine-video`，最多 7 张；不要与 `image` 同时传。

建议选项

秒数：

468 101215

grok-imagine-video 画幅：

1:116:99:16 4:33:43:22:3

grok-imagine-video-1.5-preview 画幅：

16:99:16

清晰度：

720p480p

图片推荐使用公网可直接访问的 HTTPS 直链。
支持完整 base64 data URL，例如 data:image/png;base64,...。
不要传裸 base64，例如 iVBORw0KGgo...。
图片 URL 不应依赖登录、Cookie、防盗链或临时跳转。

请求示例

文生视频

curl

curl -X POST "https://img.apixgo.com/v1/video/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A cinematic shot of a red sports car driving through rainy neon streets at night",
    "seconds": "6",
    "size": "1280x720",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

单参考图生视频

curl

curl -X POST "https://img.apixgo.com/v1/video/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "prompt": "Animate the product with a slow rotating camera, soft studio light, premium commercial style",
    "seconds": "6",
    "size": "720x1280",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "image": "https://example.com/product.png"
  }'

多参考图生视频

curl

curl -X POST "https://img.apixgo.com/v1/video/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Create a smooth product showcase video using these references, luxury lighting, clean background",
    "seconds": "10",
    "size": "1280x720",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "reference_images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ]
  }'

JavaScript 端到端示例

Node.js / Backend

const BASE_URL = 'https://img.apixgo.com';
const API_KEY = process.env.NEWAPI_API_KEY;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function validateVideoRequest({ model, imageUrls }) {
  if (model === 'grok-imagine-video-1.5-preview' && imageUrls.length !== 1) {
    throw new Error('grok-imagine-video-1.5-preview requires exactly one reference image.');
  }

  if (model === 'grok-imagine-video' && imageUrls.length > 7) {
    throw new Error('grok-imagine-video supports at most 7 reference images.');
  }
}

async function createVideo({
  model = 'grok-imagine-video',
  prompt,
  seconds = '4',
  size = '1280x720',
  aspectRatio = '16:9',
  resolution = '720p',
  imageUrls = [],
}) {
  validateVideoRequest({ model, imageUrls });

  const body = {
    model,
    prompt,
    seconds: String(Math.max(1, Math.min(15, Number(seconds) || 4))),
    size,
    aspect_ratio: aspectRatio,
    resolution,
  };

  if (imageUrls.length === 1) {
    body.image = imageUrls[0];
  } else if (imageUrls.length > 1) {
    body.reference_images = imageUrls;
    if (imageUrls.length >= 2 && Number(body.seconds) > 10) {
      body.seconds = '10';
    }
  }

  const createResponse = await fetch(`${BASE_URL}/v1/video/generations`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  const created = await createResponse.json();
  if (!createResponse.ok) {
    throw new Error(`Video request failed: ${JSON.stringify(created)}`);
  }

  const taskId = created.task_id || created.id;
  if (!taskId) {
    throw new Error(`No task_id returned: ${JSON.stringify(created)}`);
  }

  for (let i = 0; i < 240; i += 1) {
    await sleep(5000);

    const pollResponse = await fetch(`${BASE_URL}/v1/video/generations/${taskId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    const result = await pollResponse.json();
    if (!pollResponse.ok) {
      throw new Error(`Video poll failed: ${JSON.stringify(result)}`);
    }

    const task = result.data;
    if (task?.status === 'SUCCESS') {
      const videoUrl = task.data?.video_url || task.video_url || task.result_url;
      if (videoUrl) {
        return { task_id: task.task_id, video_url: videoUrl, raw_response: result };
      }
    }

    if (task?.status === 'FAILURE') {
      throw new Error(`Video generation failed: ${task.fail_reason || JSON.stringify(result)}`);
    }
  }

  throw new Error(`Video generation timeout: ${taskId}`);
}

响应示例

创建成功

JSON

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1780000000
}

处理中

JSON

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "IN_PROGRESS",
    "progress": "30%",
    "result_url": "",
    "fail_reason": ""
  }
}

成功

JSON

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://img.apixgo.com/v1/videos/task_xxx/content",
    "fail_reason": "",
    "data": {
      "model": "grok-imagine-video",
      "status": "completed",
      "video_url": "https://vidgen.x.ai/example/generated-video.mp4"
    }
  }
}

失败

JSON

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "FAILURE",
    "progress": "100%",
    "result_url": "",
    "fail_reason": "Image URL could not be fetched: Fetching image failed with HTTP status 400 Bad Request."
  }
}

轮询与下载

轮询间隔	建议每 5 秒一次。
最大轮询时长	建议至少 20 分钟；超时后保留 task_id，稍后继续查询。
最大轮询次数	按 5 秒间隔建议至少 240 次。
成功判断	`data.status == "SUCCESS"`，优先读取 `data.data.video_url`，其次读取 `data.result_url`。
失败判断	`data.status == "FAILURE"`，读取并展示 `data.fail_reason`。

生成成功后下载

# data.data.video_url 可直接下载
curl -L -o "grok_video_$(date +%s).mp4" "$video_url"

# 若使用 data.result_url，建议携带 NewAPI Key
curl -L -H "Authorization: Bearer $API_KEY" -o "grok_video_$(date +%s).mp4" "$result_url"

临时直链

data.data.video_url 是上游临时直链；result_url 可能是需要 Bearer 鉴权的 NewAPI 内容代理。建议成功后立即下载并转存。

状态/错误码

状态或错误	含义	建议处理
`SUBMITTED` / `QUEUED` / `IN_PROGRESS` / `NOT_START`	任务仍在处理中。	继续按轮询策略查询。
`SUCCESS`	任务成功。	优先读取 `data.data.video_url`，其次读取 `data.result_url`。
`FAILURE`	任务失败。	展示 `data.fail_reason`，保留 `task_id` 便于排查。
`401`	API Key 缺失或错误。	检查 `Authorization: Bearer <YOUR_API_KEY>`。
`403`	权限、额度或分组限制。	检查账号余额、令牌权限和可用模型。
`400 prompt is required`	`prompt` 为空。	提交前要求用户填写提示词。
`400 model field is required`	`model` 为空。	使用模型列表中的模型 ID。
`400 only supports exactly one reference image`	`grok-imagine-video-1.5-preview` 没有传图或传了多张图。	该模型只传 1 张参考图。
`Text-to-video is not supported for this model`	`grok-imagine-video-1.5-preview` 收到了纯文本请求。	增加单张参考图，并使用顶层 `image` 字段。
图片抓取失败	图片 URL 无法被服务端访问。	换成真实 HTTPS 直链或完整 base64 data URL。
轮询超时	任务耗时较长或暂时没有结果。	保留 `task_id`，稍后继续查询。

注意：progress: "100%" 只表示任务流程已结束，不一定代表成功。是否成功必须看 data.status。

常见问题

可以把 API Key 放到这个页面里吗？
不可以。这个页面是静态文档，任何写入前端的 Key 都可能被用户或爬虫看到。请由后端服务调用 API。
应该写死模型 ID 吗？
不建议。页面示例使用当前已知模型，但业务代码应优先通过 /v1/models 动态读取。
多参考图最多几张？
grok-imagine-video 最多支持 7 张参考图，多参考图视频最长 10 秒。
grok-imagine-video-1.5-preview 能做文生视频吗？
当前不支持。它必须提供且只能提供 1 张参考图。
为什么任务失败时进度也是 100%？
进度 100% 只表示流程结束。请以 data.status 判断结果，并在失败时读取 data.fail_reason。
生成的视频 URL 可以长期保存吗？
不建议直接长期保存。优先读取 data.data.video_url 并立即转存；使用 result_url 下载时可能需要 Bearer Key。