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 Imagine 1.0 视频生成 API:端点、鉴权范围与错误处理
    返回全部文章
    tutorial2026-11-176 分钟阅读

    Grok Imagine 1.0 视频生成 API:端点、鉴权范围与错误处理

    当前 ToAPIs 的 Grok Imagine 约定使用 grok-imagine-video-official 与 grok-imagine-video-1.5-official:Bearer API Key 鉴权、generations 与延长端点,以及已文档化的错误与状态处理——而不是 grok-imagine-1.0 型号或 OAuth 范围矩阵。

    ToAPIs Engineering & Evaluation Team
    Grok ImagineVideo APIAuthenticationError HandlingTutorial
    TL;DR - 核心要点
    • 没有名为 grok-imagine-1.0 的公共目录型号。已文档化的官方渠道型号是 grok-imagine-video-official(文生视频、图生视频、多参考图,并可延长)和 grok-imagine-video-1.5-official(仅首帧图生视频,最高 1080p,不支持延长)。
    • 已文档化的鉴权方式是 Authorization 头中的 Bearer API Key。本文未找到这些端点的公开 OAuth 范围矩阵(例如 videos:write)。
    • 用 POST /v1/videos/generations 创建任务,并用 GET /v1/videos/generations/{id} 轮询。官方渠道片段可通过 POST /v1/videos/{video_id}/extend,或 POST /v1/videos/extend 加 video_urls 延长 2–10 秒。
    • 本地图片请先通过 POST /v1/uploads/images 上传,并只发送公开 URL。official 允许 image 与 reference_images 合计最多 7 张;1.5-official 必须恰好 1 张首帧,且未文档化视频延长。
    • 输出按分辨率档位按秒计费;输入图片按张计费;延长还会对源视频时长计费。请在账户中确认实时费率,不要沿用稿件中的单价。

    Grok Imagine 1.0 视频生成 API:端点、鉴权范围与错误处理

    目标型号:grok-imagine-video-official、grok-imagine-video-1.5-official
    推理接口:https://api.toapis.com/v1/videos/generations
    相关阅读:Grok Video 实操指南 · OpenAI 兼容接入 · 官方 Imagine 生成 · 官方 Imagine 延长


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

    • 型号:标题里的“Grok Imagine 1.0”需要落到 ToAPIs 实际公布的字符串。日期为 2026-11-10 的公共目录快照列出了 grok-imagine-video-official 与 grok-imagine-video-1.5-official(这两个型号同时出现在 image-generation 和 openai-video 下)。2026-11-17 检查 grok-imagine-1.0 文档路径时返回 HTTP 404。
    • 鉴权:发送 Authorization: Bearer $TOAPIS_API_KEY。官方页面没有为这些调用文档化 OAuth 范围、细粒度权限名,或范围发现端点。
    • 端点:用 POST /v1/videos/generations 创建,用 GET /v1/videos/generations/{id} 轮询。延长官方渠道输出使用 POST /v1/videos/{video_id}/extend;若只有公开视频 URL,则使用 POST /v1/videos/extend 并传入 video_urls。静帧上传走 POST /v1/uploads/images。
    • 能力:grok-imagine-video-official 覆盖文生视频、图生视频和多参考图,分辨率为 480p 或 720p,时长 1–15 秒,并可延长 2–10 秒。grok-imagine-video-1.5-official 仅支持首帧图生视频,必须恰好 1 张 image,允许 1080p,并且不支持延长。
    • 计费形态(参考页没有固定单价):输出按分辨率档位按秒计费;每张输入图片按张计费;延长还会对源视频时长计费。请确认账户实时费率。

    2. 端点、鉴权与型号约定

    官方文档使用 https://toapis.com(中国大陆使用 https://toapis.cn)。本系列其他指南使用 https://api.toapis.com。请选定一个源站并保持一致。下列路径都使用同一个 Bearer 请求头。

    操作方法与路径型号说明
    上传静帧POST /v1/uploads/imagesMultipart file。JPEG、PNG、WebP 或 GIF,最大 30 MB。读取 data.url
    创建视频POST /v1/videos/generations两个官方 Imagine 型号都适用
    查询状态GET /v1/videos/generations/{id}生成与延长任务使用同一路径
    基于先前任务延长POST /v1/videos/{video_id}/extend仅 grok-imagine-video-official。video_id 是上一次生成任务的 id
    基于公开 URL 延长POST /v1/videos/extend同一官方型号;没有路径 id 时必须提供 video_urls
    目录型号文档化任务时长分辨率图片延长
    grok-imagine-video-official文生视频、首帧和多参考图1–15 秒(默认 8)480p、720p可选 image 加上 reference_images;合计最多 7 张2–10 秒(duration 默认 6)
    grok-imagine-video-1.5-official仅首帧图生视频1–15 秒(默认 8)480p、720p、1080pimage 必填(恰好 1 张首帧)。额外的 reference_images 仍计入 7 张上限不支持

    官方 Imagine 参考中的宽高比包括 16:9、9:16、4:3、3:4、3:2、2:3 和 1:1。请发送你已为该型号和渠道确认过的值。

    文档中没有用于分别申请“生成”“延长”或“上传”的公开范围字符串。访问权限取决于 API Key、用户组和渠道配置已经允许的范围。若调用因权限或可用性失败,应检查该密钥的模型列表和 错误参考,而不是追加一个自造的 scope 查询参数。

    凭证节点经六边形网关进入三个端点卡片

    图 1:一把 Bearer API Key 即可授权上传、生成或延长,以及状态轮询;官方 1.5 型号不会增加延长分支。

    非官方的 Grok Video 家族(grok-video-1.0 / grok-video-1.5)见 Grok Video 实操指南。那些型号是另一套约定,并不继承本页的延长路径。


    3. 生产级实现:cURL 与 Python

    步骤 1:cURL — 官方渠道文生视频

    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-imagine-video-official",
        "prompt": "A golden retriever running on a green field in sunny weather",
        "duration": 10,
        "resolution": "720p",
        "aspect_ratio": "16:9"
      }'
    

    在 grok-imagine-video-1.5-official 上做首帧任务时使用同一路径,必须提供 "image": "https://example.com/portrait.jpg",并可将 "resolution": "1080p"。请把示例 URL 换成可访问的公开地址——若文件在本地,请先上传:

    bash
    curl -X POST "https://api.toapis.com/v1/uploads/images" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -F "file=@/path/to/first-frame.jpg"
    

    步骤 2:Python — 生成、轮询与可选延长

    python
    import os
    import time
    import requests
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE = "https://api.toapis.com"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    
    def dispatch_imagine(
        prompt: str,
        *,
        model: str = "grok-imagine-video-official",
        duration: int = 10,
        resolution: str = "720p",
        aspect_ratio: str = "16:9",
        image_url: str | None = None,
        reference_images: list[str] | None = None,
    ) -> str:
        if model == "grok-imagine-video-1.5-official" and not image_url:
            raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
        payload = {
            "model": model,
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        }
        if image_url:
            payload["image"] = image_url
        if reference_images:
            payload["reference_images"] = reference_images
        res = requests.post(
            f"{BASE}/v1/videos/generations",
            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) -> dict:
        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={"Authorization": f"Bearer {API_KEY}"}, 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
            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")
    
    
    def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
        if not (2 <= duration <= 10):
            raise ValueError("official extend duration is documented as 2-10 seconds")
        res = requests.post(
            f"{BASE}/v1/videos/{source_task_id}/extend",
            headers=HEADERS,
            json={
                "model": "grok-imagine-video-official",
                "prompt": prompt,
                "duration": duration,
            },
            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 extend envelope: {data}")
        return task_id
    
    
    if __name__ == "__main__":
        task_id = dispatch_imagine(
            "A golden retriever running on a green field in sunny weather",
            duration=10,
            resolution="720p",
        )
        print("Task:", task_id)
        result = poll_task(task_id)
        print("Video:", result["result"]["data"][0]["url"])
    

    若要从公开 MP4 而不是任务 id 延长,请对 POST /v1/videos/extend 发送同一官方型号、提示词、duration 以及 video_urls 列表。不要用 grok-imagine-video-1.5-official 调用延长。


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

    下表是排查起点,并不保证与 ToAPIs 错误码完全一致。即便查询接口返回 HTTP 成功,也必须读取任务的 status。错误参考 区分了请求错误、失败任务的 error.reason,以及 Webhook 载荷。

    HTTP 或任务状态常见类别建议操作
    400字段无效、1.5-official 缺少必填 image、图片数量超限,或对不支持延长的型号调用了延长核对精确官方型号、时长(生成 1–15 秒,延长 2–10 秒)、分辨率(1080p 仅适用于 1.5-official),以及所有媒体值是否为公开 URL
    401缺少或无效的 API Key轮换密钥并确认 Authorization: Bearer。不要把未文档化的 scope 参数当作变通办法
    429速率或并发限制若存在 Retry-After 则遵守,并加入抖动后退避
    5xx 或客户端超时网关或上游临时问题重新提交前先查询已有任务 id
    status: queued 或 in_progress不是错误等待并再次轮询
    status: failed 且原因为 content_policy_rejected安全或版权审核检查提示词和每一份参考素材;合规输入仍可能得到被拒绝的输出
    status: failed 且原因为 insufficient_user_balance 或 token_quota_exceeded余额或 Token 额度同时检查余额和周期性限额
    status: failed 且原因为 generation_timeout、model_unavailable 或 service_busy上游超时或可用性先查询已有 id;仅在任务已结束后再按退避重试

    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

    官方 Imagine 生成与延长页面描述的是计费形态,而不是固定的公开单价:

    Estimated cost=(output seconds×resolution rate)+(input images×per-image rate)+(extend source seconds×per-second rate)\text{Estimated cost} = (\text{output seconds} \times \text{resolution rate}) + (\text{input images} \times \text{per-image rate}) + (\text{extend source seconds} \times \text{per-second rate})Estimated cost=(output seconds×resolution rate)+(input images×per-image rate)+(extend source seconds×per-second rate)

    请使用账户和 SKU 返回的费率,而不是稿件中的数字。

    • grok-imagine-video-1.5-official 始终包含一次输入图片费用,因为首帧图片是必填项。
    • 延长不是免费续写。 官方延长计费包括生成的延长秒数以及源视频时长。因此循环叠加延长时,会再次对不断变长的源片计费——在编写循环前请先对照实时报价确认这一行为。
    • 不要沿用规划稿里的单价或 SLA 数字。 ToAPIs 定价页上的官方厂商参考行仅供展示,未必等于账户扣费。
    • 先用 720p 和中等时长打样,一次只改一个变量;客户端超时后,在查清任务状态前不要重提。

    6. 常见问题

    详见 frontmatter 中的 FAQ。摘要:发送 grok-imagine-video-official 或 grok-imagine-video-1.5-official,而不是 grok-imagine-1.0;鉴权是 Bearer API Key,没有公开的 OAuth 范围矩阵;1.5-official 仅支持首帧且不能延长;延长时长为 2–10 秒,并且会对源片时长计费;始终区分 HTTP 错误与 status: failed。


    7. 行动清单

    • 在 ToAPIs 开发者门户 创建密钥。
    • 通过 GET /v1/models?type=video 确认你的密钥能看到 grok-imagine-video-official 或 grok-imagine-video-1.5-official。
    • 冒烟测试一次 720p 官方渠道生成,轮询 GET /v1/videos/generations/{id},并在 expires_at 之前下载文件。
    • 若需要续写,仅使用 grok-imagine-video-official 和 2–10 秒的 duration 做延长,并确认报价包含源时长计费。
    • 下一步:查看 官方 Imagine 型号指南 与 官方 Imagine 1.5 型号指南 了解目录现状;若你实际要接的是非官方 grok-video-* 家族,请改读 Grok Video 实操指南。

    本文提到的模型与接口

    xAIVIDEO

    grok-imagine-video-official

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

    grok-imagine-video-1.5-official

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

    相关技术文章

    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:007 分钟阅读

    Kling 3.0 Turbo API:高并发短视频自动化架构

    在 ToAPIs 上把 kling-3.0-turbo 接入生产的指南:已文档化的时长与分辨率范围、仅支持首帧的图片输入、有上限的轮询循环,以及不引用未核实规划稿价格的高频短视频自动化。

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Turbo
    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. 版权所有。