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 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. 版權所有。