MaiShouAI

主题

Grok 视频生成 API ​

本文面向通过 MaiShouAI 调用 Grok 视频模型的开发者，覆盖文生视频、图生视频、任务查询和视频下载。

Grok 视频生成采用异步任务模式，完整流程为：

text
1. 创建任务  POST /v1/videos
2. 查询任务  GET  /v1/videos/{task_id}
3. 下载视频  GET  /v1/videos/{task_id}/content

1. 基础信息 ​

项目说明
API 地址https://maishouai.top/v1
认证方式Authorization: Bearer <API_KEY>
创建请求Content-Type: application/json
创建和查询响应JSON
视频下载响应MP4 二进制流

除临时输入图片地址外，本文中的业务接口均需携带 API Key。API Key 应使用 image-video 分组，创建方法请参考创建 API Key。

2. 可用模型 ​

常见模型名称如下：

模型文生视频图生视频说明
grok-imagine-video支持支持Grok 通用视频模型
grok-imagine-video-1.5支持支持Grok 1.5 预览模型
grok-imagine-video-1.5-preview支持支持Grok 1.5 预览模型

实际开放的模型名称由站点配置决定，也可能使用自定义模型名称。接入前可调用以下接口确认：

http
GET /v1/models
Authorization: Bearer <API_KEY>

也可以前往模型广场查看当前可用模型和价格。

3. 创建视频任务 ​

http
POST /v1/videos

3.1 请求参数 ​

参数类型必填说明
modelstring是视频模型名称
promptstring是视频描述，不可为空
secondsstring否视频时长，推荐传字符串，例如 "5"
resolutionstring否清晰度：480p、720p、1080p
aspect_ratiostring否比例：1:1、16:9、9:16、4:3、3:4、3:2、2:3
image_urlstring否输入图片；不传为文生视频，传入后为图生视频

推荐使用 resolution 和 aspect_ratio 控制清晰度与画幅，不建议主动传递旧版 size 字段。

3.2 文生视频 ​

bash
curl -X POST "https://maishouai.top/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A cat running through a neon city at night, cinematic camera movement",
    "seconds": "5",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

3.3 使用公网图片进行图生视频 ​

image_url 可以是无需登录、无需额外请求头即可访问的公网图片直链：

bash
curl -X POST "https://maishouai.top/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "prompt": "The person turns naturally and smiles while the camera slowly moves forward",
    "seconds": "5",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "image_url": "https://example.com/input.png"
  }'

3.4 使用 Base64 图片进行图生视频 ​

image_url 也可以传 Base64 Data URL：

json
{
  "model": "grok-imagine-video-1.5-preview",
  "prompt": "The person turns naturally and smiles while the camera slowly moves forward",
  "seconds": "5",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "image_url": "data:image/png;base64,iVBORw0KGgoAAA..."
}

支持 PNG、JPEG 和 WebP 输入图片。

当上游渠道要求图片 URL 时，MaiShouAI 会自动：

  1. 校验并解码 Base64 图片。
  2. 将图片临时保存到服务器。
  3. 生成上游可以访问的临时图片 URL。
  4. 使用临时 URL 请求上游渠道。

临时输入图片默认保存约 24 小时，调用方不需要自行上传图床。图片大小不能超过站点配置的上传限制。

image_url 必须是字符串，不支持对象格式：

json
{
  "image_url": {
    "url": "https://example.com/input.png"
  }
}

3.5 创建成功响应 ​

json
{
  "id": "task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao",
  "task_id": "task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1785077205,
  "seconds": "5",
  "size": "720x1280"
}

保存 task_id，后续查询和下载均使用该值。id 与 task_id 通常相同。

响应中的 size 可能是上游兼容字段，不一定代表最终输出尺寸。最终画面以 resolution、aspect_ratio 和上游实际输出为准。

4. 查询任务状态 ​

http
GET /v1/videos/{task_id}
Authorization: Bearer <API_KEY>
bash
curl "https://maishouai.top/v1/videos/task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao" \
  -H "Authorization: Bearer $API_KEY"

4.1 任务状态 ​

状态说明处理方式
queued / pending等待处理继续轮询
processing / in_progress正在生成继续轮询
completed生成完成调用下载接口
failed / cancelled生成失败读取 error 字段并停止轮询

建议每 5 至 10 秒查询一次，并设置 5 至 10 分钟的总超时，不要高频或无限轮询。

完成响应示例：

json
{
  "id": "task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao",
  "task_id": "task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1785077205,
  "completed_at": 1785077265
}

失败响应示例：

json
{
  "id": "task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao",
  "task_id": "task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "Video generation failed"
  }
}

5. 下载视频 ​

任务状态变为 completed 后调用：

http
GET /v1/videos/{task_id}/content
Authorization: Bearer <API_KEY>
bash
curl "https://maishouai.top/v1/videos/task_cpNa1In8pOUQPLwsrlYsqUJnsCRZszao/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o output.mp4

接口返回视频二进制流，通常为 video/mp4。不要依赖上游临时视频 URL，统一通过该下载接口获取结果。

6. Python 完整示例 ​

下面的示例同时支持文生视频、公网 URL 图生视频和本地图片 Base64 图生视频。

python
import base64
import mimetypes
import os
import time
from pathlib import Path

import requests


API_KEY = os.environ["GWLINK_API_KEY"]
BASE_URL = "https://maishouai.top/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def image_to_data_url(path):
    image_path = Path(path)
    mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
    encoded = base64.b64encode(image_path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def generate_video(
    prompt,
    model="grok-imagine-video",
    seconds="5",
    resolution="720p",
    aspect_ratio="16:9",
    image_url=None,
    image_path=None,
    timeout=600,
    interval=8,
):
    payload = {
        "model": model,
        "prompt": prompt,
        "seconds": str(seconds),
        "resolution": resolution,
        "aspect_ratio": aspect_ratio,
    }
    if image_path:
        payload["image_url"] = image_to_data_url(image_path)
    elif image_url:
        payload["image_url"] = image_url

    response = requests.post(
        f"{BASE_URL}/videos",
        headers={**HEADERS, "Content-Type": "application/json"},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["task_id"]
    print(f"任务已创建: {task_id}")

    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/videos/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        status = task.get("status")
        print(f"状态: {status}, 进度: {task.get('progress', 0)}")

        if status == "completed":
            break
        if status in {"failed", "cancelled"}:
            error = task.get("error") or {}
            raise RuntimeError(error.get("message") or "视频生成失败")
        time.sleep(interval)
    else:
        raise TimeoutError(f"任务查询超时: {task_id}")

    output_path = Path(f"{task_id}.mp4")
    with requests.get(
        f"{BASE_URL}/videos/{task_id}/content",
        headers=HEADERS,
        stream=True,
        timeout=180,
    ) as response:
        response.raise_for_status()
        with output_path.open("wb") as output:
            for chunk in response.iter_content(chunk_size=64 * 1024):
                if chunk:
                    output.write(chunk)

    print(f"视频已保存: {output_path}")
    return output_path


if __name__ == "__main__":
    # 文生视频
    generate_video("A cat running through a neon city, cinematic")

    # 公网 URL 图生视频
    # generate_video(
    #     "The person turns naturally and smiles",
    #     model="grok-imagine-video-1.5-preview",
    #     image_url="https://example.com/input.png",
    # )

    # 本地图片 Base64 图生视频
    # generate_video(
    #     "The person turns naturally and smiles",
    #     model="grok-imagine-video-1.5-preview",
    #     image_path="input.png",
    # )

7. 常见错误 ​

HTTP 状态码错误码或场景处理方式
400invalid_request检查 model、prompt 等必填参数
400invalid_json检查 JSON 格式和字段类型，seconds 建议传字符串
400invalid_video_input_imageBase64 无效、文件不是图片、格式不支持或超过大小限制
400task_not_exist任务不存在，或任务不属于当前 API Key 用户
401API Key 无效检查 Authorization: Bearer ...
400 / 422上游拒绝请求检查时长、分辨率、画幅和模型能力
500 / 502上游或服务异常稍后重试；持续出现时联系服务提供方

创建接口返回错误表示任务未成功创建。任务创建成功后，也可能在生成过程中变为 failed，因此必须同时处理 HTTP 错误和任务失败状态。

8. 接入检查清单 ​

  • [ ] 使用 POST /v1/videos 创建任务。
  • [ ] seconds 使用字符串，例如 "5"。
  • [ ] 使用 resolution 和 aspect_ratio，不主动传 size。
  • [ ] 图生视频使用顶层字符串字段 image_url。
  • [ ] Base64 图片使用 data:image/png;base64,... 格式。
  • [ ] 每 5 至 10 秒轮询一次任务状态。
  • [ ] 处理 completed、failed 和 cancelled 状态。
  • [ ] 所有业务请求均携带 API Key。
  • [ ] 视频通过 /v1/videos/{task_id}/content 下载。
  • [ ] 客户端设置总超时，避免无限轮询。

一个 API Key 畅享所有大模型

Copyright © 2026 MaiShouAI