ToAPIs
    首页ToAPIs
    图片生成GPT Image 2.6、Gemini 图像…视频生成Seedance、Veo、Kling、Sora…聊天与写作GPT-5.6、Claude、DeepSeek…语音与音乐配音、语音合成、播客
    新上线Seedance 2.5
    价格API 文档MCP
    博客竞品替代
    登录免费试用
    全部模型价格API 文档MCP博客竞品替代
    登录免费试用

    语言

    Esc
    • Seedance 2.5视频生成
    • GPT Image 2图片生成
    • GPT Image 2.6图片生成
    • GPT Image 2.5图片生成
    • Veo 3.1 Fast视频生成
    • Kling 3.0 Turbo视频生成
    • Kling V4 Flash视频生成
    • Grok Video 1.5视频生成
    • Nano Banana 2图片生成
    • Seedream 5.5图片生成
    • FLUX图片生成
    • Sora 2视频生成
    • 全部图片模型用途
    • 全部视频模型用途
    • GPT-5.6 Sol聊天与写作
    • Claude Opus 4.8聊天与编程
    • Claude Opus 4.7聊天与编程
    • DeepSeek V4 ProDeepSeek · 文字
    • Gemini Omni 1.1 FlashGoogle · 多模态
    1. 首页
    2. 博客
    3. 开发教程
    4. 上手 Grok-Video-3 API:关于 xAI 视频引擎,你需要先弄清的当前约定
    返回全部文章
    tutorial2026-11-176 分钟阅读

    上手 Grok-Video-3 API:关于 xAI 视频引擎,你需要先弄清的当前约定

    在 ToAPIs 上调用 xAI Grok Video 的实操指南:当前公共目录列出的是 grok-video-1.0 与 grok-video-1.5,而不是 grok-video-3;本文说明现有 generations 约定、生成模式与轮询路径。

    ToAPIs Engineering & Evaluation Team
    Grok VideoVideo APIxAIText-to-VideoTutorial
    TL;DR - 核心要点
    • 公共目录快照日期为 2026-11-10;2026-11-17 复查文档与型号指南页面后,ToAPIs 仍没有名为 grok-video-3 的公共型号。已文档化的 Grok Video 型号是 grok-video-1.0 与 grok-video-1.5。
    • 使用 Bearer API Key 向 POST /v1/videos/generations 提交任务,持久化任务 id,并轮询 GET /v1/videos/generations/{id}。不要调用未文档化的 /videos/tasks 路径。
    • grok-video-1.5 文档写明三种显式模式:text_to_video、first_frame_image_to_video、reference_images_to_video。video_generation_mode 必须与实际发送的媒体一致。
    • 图片必须是可公开访问的 http(s) URL。本地文件请先通过 POST /v1/uploads/images 上传;这些生成接口不接受 base64。
    • 不要沿用规划稿里未核实的每秒单价或 SLA 数字。预测镜头成本前,请在账户中确认当前费率和渠道是否开放。

    上手 Grok-Video-3 API:关于 xAI 视频引擎,你需要先弄清的当前约定

    目标型号:grok-video-1.5、grok-video-1.0
    推理接口:https://api.toapis.com/v1/videos/generations
    相关阅读:OpenAI 兼容接入 · Grok Imagine 官方渠道 API · Hailuo 2.3 视频指南 · Grok Video 1.5 参考


    1. 核心摘要与性能速览 (TL;DR)

    • 先看目录:即便标题是 Grok Video 3 实操,接入也必须从 ToAPIs 实际公布的型号开始。日期为 2026-11-10 的公共生产目录快照,在 openai-video 端点下列出的是 grok-video-1.0 与 grok-video-1.5。2026-11-17 检查 grok-video-3 的文档和型号指南 URL,返回的是 HTTP 404。
    • 约定:向 POST /v1/videos/generations 异步提交,再轮询 GET /v1/videos/generations/{id},直到 completed 或 failed。官方示例使用 https://toapis.com(中国大陆使用 https://toapis.cn)。本系列其他指南使用 https://api.toapis.com。请选定一个源站并保持一致。
    • 模式:grok-video-1.5 文档写明 text_to_video、first_frame_image_to_video 和 reference_images_to_video。请显式填写 video_generation_mode,避免单张参考图被当成旧版首帧请求。
    • 媒体:只发送可公开访问的 http:// 或 https:// URL。本地文件先通过 POST /v1/uploads/images 上传,并使用返回的 data.url。不要发送 base64。
    • 应丢弃的未核实表述:规划稿里的 grok-video-3 型号、99.95% SLA、固定 $0.030–$0.038 每秒单价,或未来音频上线日期,都不是当前 ToAPIs 文档内容。请在账户中确认实时费率和渠道是否开放。

    2. 当前 Grok Video 型号与生成模式

    在 model 字段中使用公共型号名。不要替换成供应商原生名称、URL slug,或尚未公布的 grok-video-3 字符串。

    目录型号文档化任务时长(文档)分辨率图片输入
    grok-video-1.5文生视频、首帧,或 1–7 张参考图,由 video_generation_mode 指定整数 1–15 秒参考图模式为 480p 或 720p;文生视频和首帧在渠道支持时可使用 1080p首帧:恰好 1 张 image 或 input_reference。参考图模式:1–7 张 reference_images
    grok-video-1.0文生视频与图生视频生成参考:1–15 秒(默认 8)。型号指南 / Playground:当前可用变体存在 6 秒 上限480p、720p可选 image 加上 reference_images;合计最多 8 张

    对于 grok-video-1.5,新接入应显式指定模式:

    video_generation_mode必填输入必须省略
    text_to_video非空 prompt任何图片字段
    first_frame_image_to_video在 image 或 input_reference 中恰好 1 张首帧两个别名传了互相冲突的值;除非你的账户参考另有说明,否则不要同时再传参考图列表
    reference_images_to_videoprompt 加上 1–7 张 reference_images(字符串或 {"url":"..."} 对象)只传一张 reference_images 却不带该模式——旧版单图输入仍会按首帧处理

    报价成功并不保证生成渠道已经开放。模式只有在兼容渠道启用后才能使用;不支持的组合可能在创建任务之前就被拒绝。

    Grok Video 参考中的常见宽高比为 16:9、9:16、3:2、2:3 和 1:1。具体是否可用仍取决于渠道,请发送你已为该型号确认过的值。

    空白输入帧穿过六边形网关,形成单一输出画面

    图 1:把提示词(以及可选的公开图片 URL)提交到 POST /v1/videos/generations,轮询同一个任务 id,仅在 status 为 completed 后读取 result.data[0].url。

    若你需要官方渠道 Grok Imagine 的视频延长等能力,那是另一组型号,见 Imagine 官方渠道指南。若要对照另一套时长矩阵,见 Hailuo 2.3 指南。


    3. 生产级实现:cURL 与 Python

    本系列面向国际环境的示例使用 https://api.toapis.com。官方文档要求中国大陆用户使用 https://toapis.cn。每个环境只保留一个源站。路径、型号 ID 和 Bearer 请求头保持不变。

    步骤 1:使用 cURL 提交 grok-video-1.5

    bash
    curl -X POST "https://api.toapis.com/v1/videos/generations" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "grok-video-1.5",
        "prompt": "A cinematic product shot with a slow camera push-in",
        "video_generation_mode": "text_to_video",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "16:9"
      }'
    

    首帧任务使用同一路径,将 "video_generation_mode": "first_frame_image_to_video" 与 image URL 一起发送。参考图任务设置 "video_generation_mode": "reference_images_to_video" 和 reference_images 列表,并把 resolution 保持在 480p 或 720p。

    步骤 2:Python 提交与轮询助手

    下面的示例遵循文档中的任务状态路径,以及 queued / in_progress / completed / failed 状态。上线前请对照你账户的 API 参考,确认 id、result.data[0].url 和响应结构。

    python
    import os
    import time
    import requests
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE = "https://api.toapis.com"
    ENDPOINT = f"{BASE}/v1/videos/generations"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    
    def dispatch_grok_video(
        prompt: str,
        *,
        model: str = "grok-video-1.5",
        mode: str = "text_to_video",
        duration: int = 8,
        resolution: str = "720p",
        aspect_ratio: str = "16:9",
        image_url: str | None = None,
        reference_images: list[str] | None = None,
    ) -> str:
        if model == "grok-video-3":
            raise ValueError("grok-video-3 is not a current public catalog ID")
        if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
            raise ValueError("reference mode is documented as 480p or 720p")
        payload = {
            "model": model,
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        }
        if model == "grok-video-1.5":
            payload["video_generation_mode"] = mode
        if mode == "text_to_video" and (image_url or reference_images):
            raise ValueError("text_to_video rejects image fields")
        if mode == "first_frame_image_to_video":
            if not image_url:
                raise ValueError("first-frame mode requires exactly one image URL")
            payload["image"] = image_url
        if mode == "reference_images_to_video":
            refs = reference_images or []
            if not (1 <= len(refs) <= 7):
                raise ValueError("reference mode requires 1-7 image URLs")
            payload["reference_images"] = refs
        res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
        res.raise_for_status()
        data = res.json()
        task_id = data.get("id") or data.get("task_id")
        if not task_id:
            raise RuntimeError(f"Unexpected submission envelope: {data}")
        return task_id
    
    
    def poll_task(task_id: str, deadline_s: int = 600) -> str:
        poll_url = f"{BASE}/v1/videos/generations/{task_id}"
        interval = 10.0
        start = time.time()
        time.sleep(5)
        while time.time() - start < deadline_s:
            poll = requests.get(poll_url, headers=HEADERS, timeout=15)
            if poll.status_code == 429:
                retry_after = poll.headers.get("Retry-After")
                time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
                continue
            poll.raise_for_status()
            data = poll.json()
            status = data.get("status")
            if status == "completed":
                return data["result"]["data"][0]["url"]
            if status == "failed":
                raise RuntimeError(f"Generation failed: {data.get('error')}")
            time.sleep(interval)
            interval = min(interval * 1.5, 30.0)
        raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
    
    
    if __name__ == "__main__":
        task_id = dispatch_grok_video(
            "A cinematic product shot with a slow camera push-in",
            mode="text_to_video",
            duration=8,
            resolution="720p",
        )
        print("Task:", task_id)
        print("Video:", poll_task(task_id))
    

    请把提示词模板版本与任务记录一起保存,以便区分型号/模式变化和措辞变化。在 expires_at 之前下载文件;状态参考写明保留期为 30 天。


    4. 错误处理与状态码对照

    下表是排查起点,并不保证与 ToAPIs 错误码完全一致。即便查询接口返回 HTTP 成功,也必须读取任务的 status。请求错误与 status: failed 的原因(如 content_policy_rejected、insufficient_user_balance、generation_timeout)见 错误参考。

    HTTP 或任务状态常见类别建议操作
    400字段无效、模式与媒体不匹配,或不支持的组合核对精确目录型号、video_generation_mode 是否与图片字段一致、参考图模式是否保持 480p 或 720p,以及图片值是否为公开 URL
    401缺少或无效的 API Key在 ToAPIs 控制台轮换密钥,并确认 Authorization: Bearer 请求头
    429速率或并发限制若存在 Retry-After 则遵守;加入抖动后退避;仅在安全时重试
    5xx 或客户端超时网关或上游临时问题重新提交前先查询已有任务 id
    status: queued 或 in_progress不是错误等待并再次轮询;不要创建第二个任务
    status: failed生成未成功读取 error.code 和 error.message(如有则包括 error.reason)。不要原样重试已被策略拒绝的请求体

    WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)WaitTime=min(MaxWait,BaseInterval×2attempt)+Uniform(0,1)


    5. 定价与 FinOps ROI

    Estimated cost=successful billable jobs×current account rate for that model, duration, and resolution\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}Estimated cost=successful billable jobs×current account rate for that model, duration, and resolution

    • 不要沿用规划稿里的单价。 grok-video-1.5 的 API 参考写明,定价以当前账户和 SKU 配置为准,该页不保证固定的每秒价格。ToAPIs 定价页上的官方厂商参考行仅供展示,未必等于账户实际扣费。
    • 报价不是渠道保证。 1.5 参考明确指出:报价成功并不意味着生成渠道可用。
    • 在提示词层控制成本:先用 720p 和 8 秒左右的中等时长打样,保留版本化模板,一次只改一个变量;客户端超时后,先查任务状态再决定是否重提。
    • 官方厂商合同常带年度承诺、席位配额和预付门槛。ToAPIs 计费通常是按量付费——请确认账户上的现行条款。

    6. 常见问题

    详见 frontmatter 中的 FAQ。摘要:grok-video-3 不是当前公共目录型号;请从 grok-video-1.5 或 grok-video-1.0 起步;把 1.0 的时长上限当作渠道相关检查;同步音频未经文档化;始终轮询 generations 状态路径并持久化任务 id。


    7. 行动清单

    • 在 ToAPIs 开发者门户 创建密钥。
    • 通过 GET /v1/models?type=video 确认你的密钥能看到 grok-video-1.5 或 grok-video-1.0——除非该 ID 随后同时出现在列表和 API 参考中,否则不要发送 grok-video-3。
    • 用 video_generation_mode: "text_to_video"、duration: 8 和 resolution: "720p" 冒烟测试上述 cURL 示例。
    • 在有截止时间的前提下轮询 GET /v1/videos/generations/{id},并在 expires_at 之前下载结果。
    • 下一步:若要把现有客户端指向 ToAPIs,请阅读 OpenAI 兼容接入指南;查看 Grok Video 1.5 型号指南 了解目录现状;在 1.0 上依赖超过 6 秒的时长前,先核对 Grok Video 1.0 型号指南。

    本文提到的模型与接口

    xAIVIDEO

    grok-video-1.0

    当前费率:2 credits /second
    模型解析页在线试跑获取 API Key
    xAIVIDEO

    Grok Video 1.5

    当前费率:3.824 credits /second
    模型解析页在线试跑获取 API Key

    相关技术文章

    tutorial2026-11-17T10:00:00+08:005 分钟阅读

    如何通过 OpenAI 兼容接口调用 Grok Video 3 API

    把 OpenAI 兼容客户端指向 ToAPIs,调用当前 Grok Video 目录型号:共享 Bearer 鉴权与 /v1 源站,视频任务走 POST /v1/videos/generations,而不是未公布的 grok-video-3 路径。

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    tutorial2026-11-20T10:00:00+08:008 分钟阅读

    阿里 Wan 3.0 视频 API 入门:下一代视频生成快速上手

    在 ToAPIs 上调用 wan3.0-video 与 wan3.0-video-prime 的生产入门:同一套 All-in-One 接口、首尾帧与参考素材的互斥规则、文件或网页引用、视频编辑约束,以及已文档化的轮询路径。

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0
    tutorial2026-11-18T10:00:00+08:008 分钟阅读

    Kling 3.0 Omni API 深挖:多镜头视频生成与物理连贯性

    在 ToAPIs 上调用 kling-v3-omni 的实操指南:官方 Omni 占位符、image_list / video_list / element_list、首尾帧,以及已文档化的轮询路径——不使用未文档化的 shots 数组。

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Omni
    ToAPIs
    首页ToAPIs
    企业级 AI API 网关,通过统一接口接入 GPT-5、Claude、Gemini 等 200+ 模型。

    热门模型

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    展开更多收起
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • 所有模型

    API 品类

    • AI 图像生成 API
    • AI 视频生成 API
    • 文生视频 API
    • 图生视频 API
    展开更多收起
    • AI 图像编辑 API
    • 语言与推理模型 API
    • 全部 API 工具 →

    替代方案

    替代方案
    • Kie.ai 替代方案
    • Fal.ai 替代方案
    • OpenRouter 替代方案
    • Replicate 替代方案
    • Wavespeed AI 替代方案
    • 全部竞品对比 →

    精选技术指南

    精选技术指南
    • Seedance 2.0 与 2.5 价格对比
    • 低成本 Seedance API 接入指南
    • MiniMax H3 接入指南
    • Seedance 2 免费测试 Key
    • Seedance 2 API 快速开始
    • 全部技术文章 →

    开发者与平台

    开发者与平台
    • API 开发文档
    • MCP
    • 定价
    • 在线模型测试台
    • LLMs.txt
    • 联系支持
    • 模型指南索引
    运营主体:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    注册地址:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    隐私政策服务条款使用政策数据删除政策数据留存政策子处理方与数据区域计费与退款说明Cookie 政策网站地图关于我们

    © 2026 ToAPIs. 版权所有。