视频生成请求文档

Developer Docs / Video Generation

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

视频生成是异步任务。创建接口会返回 task_id 或 id，客户端需要保存该 ID，并持续查询任务状态，直到成功返回 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-image-video。如果使用 grok-video-1.5，当前必须提供且只能提供 1 张参考图。

中转站接入提醒

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

请求流程

读取模型
调用 GET /v1/models 获取当前可用模型，避免把模型列表写死。
创建任务
调用 POST /v1/video/generations，提交提示词、秒数、画幅和参考图。
保存任务 ID
使用 response.task_id || response.id 作为后续查询 ID。
轮询结果
每 5 秒查询一次，成功后立即下载 result_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-image-video`

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

`grok-video-1.5`

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

请求参数

字段	类型	必填	说明
`model`	string	是	模型 ID，例如 `grok-image-video`。
`prompt`	string	是	视频提示词，不能为空。
`seconds`	integer	否	视频秒数，默认建议 4。多参考图建议不超过 10。
`aspect_ratio`	string	否	画幅比例，默认建议 `16:9`。
`resolution`	string	否	清晰度，建议 `720p` 或 `480p`。
`image_urls`	array<string>	否	参考图 URL 或完整 base64 data URL 列表，推荐优先使用。
`input_reference`	object/string	否	单参考图字段，可传 `{ "image_url": "..." }`。
`reference_images`	array<string>	否	多参考图字段。不要与 `input_reference` 同时传。

建议选项

秒数：

468 101215

grok-image-video 画幅：

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

grok-video-1.5 画幅：

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-image-video",
    "prompt": "A cinematic shot of a red sports car driving through rainy neon streets at night",
    "seconds": 6,
    "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-image-video",
    "prompt": "Animate the product with a slow rotating camera, soft studio light, premium commercial style",
    "seconds": 6,
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "image_urls": [
      "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-image-video",
    "prompt": "Create a smooth product showcase video using these references, luxury lighting, clean background",
    "seconds": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "image_urls": [
      "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-video-1.5' && imageUrls.length !== 1) {
    throw new Error('grok-video-1.5 only supports exactly one reference image.');
  }

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

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

  const body = {
    model,
    prompt,
    seconds,
    aspect_ratio: aspectRatio,
    resolution,
  };

  if (imageUrls.length > 0) {
    body.image_urls = 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 < 60; 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' && task.result_url) {
      return { task_id: task.task_id, video_url: task.result_url, 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-image-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://example.com/generated-video.mp4",
    "fail_reason": ""
  }
}

失败

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 秒一次。
最大轮询时长	建议 5 分钟。
最大轮询次数	60 次。
成功判断	`data.status == "SUCCESS"` 且 `data.result_url` 非空。
失败判断	`data.status == "FAILURE"`，读取并展示 `data.fail_reason`。

生成成功后下载

curl -L -o "grok_video_$(date +%s).mp4" "$result_url"

临时直链

result_url 有效期约 1 小时。建议生成成功后立即下载，并把视频保存到自己的对象存储或业务文件系统。

状态/错误码

状态或错误	含义	建议处理
`SUBMITTED` / `QUEUED` / `IN_PROGRESS` / `NOT_START`	任务仍在处理中。	继续按轮询策略查询。
`SUCCESS`	任务成功。	读取 `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-video-1.5` 没有传图或传了多张图。	该模型只传 1 张参考图。
图片抓取失败	图片 URL 无法被服务端访问。	换成真实 HTTPS 直链或完整 base64 data URL。
轮询超时	任务耗时较长或暂时没有结果。	保留 `task_id`，稍后继续查询。

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

常见问题

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