跳到主要内容

Grok Video API 接入文档

本文档面向使用本服务的 API 用户，说明如何通过公网 API 创建视频生成任务、查询任务状态并获取最终视频地址。

1. 基础信息​

Base URLhttps://api.constreet.cc
鉴权方式Authorization: Bearer <YOUR_API_KEY>
请求格式Content-Type: application/json
响应格式JSON
模型列表GET /v1/models
创建视频任务POST /v1/video/generations
查询视频任务GET /v1/video/generations/{task_id}

视频生成是异步任务。创建接口会先返回一个 task_id，客户端需要保存该 ID，并继续调用查询接口，直到任务成功或失败。

2. 获取 API Key​

请在用户控制台创建或复制 API Key。调用接口时放入请求头：

Authorization: Bearer <YOUR_API_KEY>

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

3. 查询可用模型​

curl -X GET "https://api.constreet.cc/v1/models"\
 -H "Authorization: Bearer <YOUR_API_KEY>"

当前开放的视频模型：

grok-image-video通用默认模型支持，最长 15 秒支持，最长 15 秒支持，最长 10 秒多参考图请求超过 10 秒时会自动按 10 秒处理
grok-video-1.5单图生视频预览模型不支持支持，最长 15 秒不支持必须提供且只能提供 1 张参考图

模型列表以 GET /v1/models 的返回为准。如果后续开放更多模型，请优先使用模型列表接口动态读取。

4. 创建视频任务​

接口：

POST /v1/video/generations

请求字段：

modelstring是模型 ID，例如 grok-image-video
promptstring是视频提示词
secondsinteger否视频秒数，默认建议 4
aspect_ratiostring否画幅比例，默认建议 16:9
resolutionstring否清晰度，建议 720p 或 480p
image_urlsarray<string>否参考图 URL 或 base64 data URL 列表
input_referenceobject/string否单参考图字段，可传 { "image_url": "..." }
reference_imagesarray<string>否多参考图字段

推荐优先使用统一的 image_urls 字段，由服务端根据模型和图片数量自动转换。

5. 参数建议​

seconds 建议选项：

[4, 6, 8, 10, 12, 15]

模型时长规则：

  • grok-image-video 文生视频、单图生视频最长支持 15 秒。
  • grok-image-video 多参考图生视频最长支持 10 秒；如果请求超过 10 秒，服务会自动按 10 秒处理。
  • grok-video-1.5 只支持单图生视频，最长支持 15 秒。

多参考图推荐选项：

[4, 6, 8, 10]

aspect_ratio 建议选项：

  • grok-image-video
["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"]
  • grok-video-1.5
["16:9", "9:16"]

resolution 建议选项：

["720p", "480p"]

图片要求：

  • 推荐使用公网可直接访问的 HTTPS 图片直链。
  • 支持完整 base64 data URL，例如 data:image/png;base64,...。
  • 不要传裸 base64，例如 iVBORw0KGgo...。
  • 图片 URL 不应依赖登录、Cookie、防盗链或临时跳转。
  • 如果上游无法抓取图片，任务会失败并返回图片抓取错误。

6. 请求示例​

6.1 文生视频​

curl -X POST "https://api.constreet.cc/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"
 }'

6.2 单参考图生视频​

curl -X POST "https://api.constreet.cc/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"
   ]
 }'

也可以使用 input_reference：

{

 "model": "grok-image-video",
 "prompt": "Animate the product with a slow rotating camera",
 "seconds": 6,
 "aspect_ratio": "9:16",
 "resolution": "720p",
 "input_reference": {
   "image_url": "https://example.com/product.png"
 }
}

6.3 多参考图生视频​

curl -X POST "https://api.constreet.cc/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"
   ]
 }'

规则：

  • grok-image-video 最多支持 7 张参考图。
  • 多参考图最长支持 10 秒；如果传入 seconds 大于 10，服务会自动按 10 秒处理。
  • 不要同时传 input_reference 和 reference_images。

6.4 grok-video-1.5 单图生视频​

curl -X POST "https://api.constreet.cc/v1/video/generations" \
 -H "Authorization: Bearer <YOUR_API_KEY>" \
 -H "Content-Type: application/json" \
 -d '{
   "model": "grok-video-1.5",
   "prompt": "Use the reference image as the main subject and create a smooth cinematic motion",
   "seconds": 4,
   "aspect_ratio": "16:9",
   "resolution": "480p",
   "image_urls": [
     "https://example.com/reference.png"
   ]
 }'

该模型当前只支持 1 张参考图，最长支持 15 秒。不要用它提交纯文生视频，也不要传多张参考图。

7. 创建响应​

创建成功后会返回任务对象。关键字段是 id 或 task_id：

{
 "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "object": "video",

 "model": "grok-image-video",
 "status": "queued",
 "progress": 0,
 "created_at": 1780000000
}

客户端应保存：

task_id = response.task_id || response.id

8. 查询任务状态​

curl -X GET "https://api.constreet.cc/v1/video/generations/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -H "Authorization: Bearer <YOUR_API_KEY>"

典型处理中响应：

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

典型成功响应：

{
 "code": "success",
 "message": "",
 "data": {
   "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "status": "SUCCESS",
   "progress": "100%",
   "result_url": "https://example.com/generated-video.mp4",
   "fail_reason": ""
 }
}

典型失败响应：

{
 "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."
 }
}

判断规则：

data.status == "SUCCESS" 且 data.result_url 非空生成成功
data.status == "FAILURE"生成失败，读取 data.fail_reason
data.status 为 SUBMITTED、QUEUED、IN_PROGRESS、NOT_START任务仍在处理中

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

建议轮询策略：

轮询间隔每 5 秒一次
最大轮询时长5 分钟
最大轮询次数60 次
成功取值data.result_url

下载示例：

# 生成成功后立即下载（推荐）
curl -L -o "grok_video_$(date +%s).mp4" "$result_url"

⚠️ result_url 为临时直链，有效期约 1 小时，建议生成成功后立即下载。推荐在业务代码中加入自动下载逻辑。

9. JavaScript 示例​

const BASE_URL = 'https://api.constreet.cc'
const API_KEY = process.env.NEWAPI_API_KEY

function sleep(ms) {
 return 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) {
     // Multi-reference video is capped at 10 seconds.
     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}`)
}

10. 常见错误​

401API Key 缺失或错误检查 Authorization: Bearer <YOUR_API_KEY>
403权限、额度或分组限制检查账号余额、令牌权限和可用模型
400 prompt is requiredprompt 为空提交前要求用户填写提示词
400 model field is requiredmodel 为空使用模型列表中的模型 ID
400 only supports exactly one reference imagegrok-video-1.5 没有传图或传了多张图该模型只传 1 张参考图
图片抓取失败图片 URL 无法被服务端访问换成真实直链或 base64；不要使用本地或需登录的地址
任务 FAILURE上游生成失败、图片不可访问或参数不支持读取 data.fail_reason 并展示给用户
轮询超时任务耗时较长或暂时没有结果保留 task_id，稍后继续查询

11. 接入注意事项​

  • 不要把模型 ID 写死成单个模型，建议通过 /v1/models 动态读取。
  • 默认推荐使用 grok-image-video。
  • grok-video-1.5 当前仅用于单参考图生视频。
  • grok-image-video 文生视频、单图生视频最长 15 秒，多参考图最长 10 秒。
  • grok-image-video 多参考图最多 7 张；多参考图请求超过 10 秒会自动按 10 秒处理。
  • grok-video-1.5只支持单图生视频，最长 15 秒。
  • 最终视频 URL 在查询接口的 data.result_url 字段中。⚠️result_url 为临时直链，有效期约 1 小时，建议生成成功后立即下载。
  • 任务失败时可能会显示 progress: "100%"，这是正常的结束状态；请以 data.status 判断成功或失败。