> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Videos Generation API 對接說明

> Grok 整合指南 - Ace Data Cloud

本文將介紹 Grok Videos Generation API 的對接說明，它可以通過輸入文本提示詞、輸入圖片以及可選的參考圖片來生成 Grok Imagine（xAI）視頻。

## 申請流程

要使用 Grok Videos Generation API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。

**一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。

> 📘 完整文檔：[Grok Videos Generation API →](https://platform.acedata.cloud/documents/grok-videos)

## 模型說明

本 API 通過模型名的後綴選擇上游端點：`:reverse` 走快速/標準端點（更便宜），`:official` 走官方端點（畫質更高，按輸出秒數計費）。共支持四個模型：

* `grok-imagine-video-1.5-fast:reverse`（默認）：支持文生視頻（僅傳 `prompt`）和圖生視頻（傳 `image_url`），時長 6–30 秒，按時長分檔計費，最便宜。
* `grok-imagine-video:reverse`：支持文生與圖生視頻，時長 1–15 秒，按輸出秒數計費。
* `grok-imagine-video:official`：官方端點，支持文生與圖生視頻，時長 1–15 秒，按輸出秒數計費，畫質更高。
* `grok-imagine-video-1.5:official`：官方端點，**僅支持圖生視頻**，**必須**傳入 `image_url`，時長 1–15 秒，支持最高 `1080p`，按輸出秒數計費。

## 基本使用

首先了解下基本的使用方式，輸入提示詞 `prompt`、模型 `model` 等參數，便可生成對應的視頻。

可以看到這裡我們設置了 Request Headers，包括：

* `accept`：想要接收怎樣格式的響應結果，這裡填寫為 `application/json`，即 JSON 格式。
* `authorization`：調用 API 的密鑰，申請之後可以直接下拉選擇。

另外設置了 Request Body，包括：

* `prompt`：描述想要生成視頻內容的文本提示詞。做文生視頻時**必填**；傳入 `image_url` 時可選。
* `model`：生成視頻的模型，可選 `grok-imagine-video-1.5-fast:reverse`（默認）、`grok-imagine-video:reverse`、`grok-imagine-video:official` 或 `grok-imagine-video-1.5:official`。
* `image_url`：圖生視頻的輸入圖片鏈接。當 `model` 為 `grok-imagine-video-1.5:official` 時**必填**。
* `reference_image_urls`：可選的參考圖片鏈接數組，用於引導視頻的風格或內容。
* `aspect_ratio`：生成視頻的寬高比，可選 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`。
* `resolution`：輸出分辨率，可選 `480p`（默認）、`720p` 或 `1080p`。
* `duration`：生成視頻的時長（秒）。`grok-imagine-video-1.5-fast:reverse` 取值範圍 6–30，其餘模型取值範圍 1–15，默認 6。推薦使用 6 秒或 10 秒，這兩個標準時長相對穩定。
* `callback_url`：異步回調地址，設置後 API 會立即返回 `task_id`，任務完成時將結果 POST 到該地址。
* `async`：可選，設為 `true` 時接口立即返回 `task_id`，無需提供 `callback_url`，隨後通過對應的任務查詢接口輪詢獲取結果。

點擊「Try」按鈕即可進行測試，得到的結果類似如下：

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

返回結果一共有多個字段，介紹如下：

* `success`：本次視頻生成請求是否成功。
* `task_id`：本次視頻生成任務的 ID。
* `trace_id`：本次請求的跟蹤 ID，用於排查問題。
* `data`：生成的視頻結果列表。
  * `id`：生成視頻的唯一標識。
  * `video_url`：生成視頻的鏈接地址。
  * `state`：視頻生成任務的狀態，可選 `pending` / `succeeded` / `failed`。

我們只需要根據結果中 `data` 的 `video_url` 鏈接地址獲取生成的視頻即可。

對應的 CURL 代碼如下：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

對應的 Python 代碼如下：

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 圖生視頻

如果想基於一張輸入圖片生成視頻，可以傳入 `image_url`。使用 `grok-imagine-video-1.5:official` 時必須提供該字段：

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## 參考圖引導

如果想用一張或多張參考圖引導生成視頻的風格或內容，可以在 `reference_image_urls` 中傳入圖片鏈接數組：

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## 異步回調

視頻生成需要一定的處理時間。如果不希望保持長連接等待，可以傳入 `callback_url`，此時 API 會立即返回 `task_id`，任務完成後會將最終結果 POST 到該地址：

```json theme={null}
{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

立即返回的結果如下：

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## 查詢任務結果

如果使用了異步回調或希望主動查詢任務狀態，可以通過 [Grok Tasks API](https://platform.acedata.cloud/documents/grok-tasks)（`POST https://api.acedata.cloud/grok/tasks`）根據 `task_id` 查詢任務的最新狀態與結果。

## 計費說明

本服務的計費方式由 `model` 決定：

* `grok-imagine-video-1.5-fast:reverse`：按時長分檔計費，與分辨率無關——`6–10` 秒、`11–20` 秒、`21–30` 秒分別對應不同檔位價格。
* `grok-imagine-video:reverse`：按「輸出秒數」計費，總價 = 單價 × `duration`。
* `grok-imagine-video:official` 與 `grok-imagine-video-1.5:official`：官方端點，按「輸出秒數」計費，分辨率越高單價越高；官方模型即使內容審核失敗也會計費。

具體單價以定價頁為準。失敗的請求不計費，也不佔用免費額度。

## 錯誤處理

當請求出現問題時，API 會返回對應的錯誤碼與說明，常見的如下：

* `400`：請求參數有誤，例如文生視頻缺少 `prompt`，或 `grok-imagine-video-1.5:official` 缺少 `image_url`，或 `duration` 超出範圍（`grok-imagine-video-1.5-fast:reverse` 為 6–30，其餘模型為 1–15）。
* `401`：鑑權失敗，token 無效或與 API 不匹配。
* `403`：餘額不足，或提示詞命中內容審核被拒絕。
* `429`：請求過於頻繁，請稍後重試。
* `500`：視頻生成失敗或服務異常。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.