ToAPIs
    首頁ToAPIs
    圖片生成GPT Image 2.6、Gemini 圖像…影片生成Seedance、Veo、Kling、Sora…聊天與寫作GPT-5.6、Claude、DeepSeek…語音與音樂配音、語音合成、Podcast
    新上線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. 版權所有。