Hướng dẫn đầy đủ cách sử dụng Grok Text to Video API

TÓM TẮT

API chuyển văn bản thành video của Grok cho phép bạn tạo video từ một lời nhắc văn bản. Quy trình gồm gọi POST /v1/videos/generations để lấy ngay request_id, sau đó lặp truy vấn GET /v1/videos/{request_id} tới khi trạng thái là "done". Sử dụng model grok-imagine-video với giá khởi điểm $0.05/giây (480p). SDK Python của xAI giúp tự động hóa quy trình truy vấn trạng thái.

Dùng thử Apidog ngay hôm nay

Giới thiệu

xAI đã tạo ra 1.2 tỷ video chỉ trong tháng đầu triển khai API chuyển văn bản thành video (28/1/2026). Model này dẫn đầu bảng xếp hạng chuyển văn bản thành video, thể hiện khả năng mở rộng và tin cậy.

Hướng dẫn này cung cấp các bước thực tế: gửi yêu cầu đầu tiên, truy vấn kết quả, tinh chỉnh tham số, tối ưu prompt, sử dụng hình ảnh tham chiếu, mở rộng/chỉnh sửa video, và xác định khi nào nên áp dụng chuyển văn bản thành video.

💡 API này là bất đồng bộ: Giao diện của bạn không thể chờ video sẵn sàng mới hiển thị kết quả. Nếu bạn xây dựng UI tạo video, nên phát triển theo luồng truy vấn mà không tốn chi phí thử nghiệm thực tế. Sử dụng Smart Mock của Apidog để mô phỏng cả endpoint tạo video lẫn truy vấn trạng thái. Bạn có thể xây dựng UI video player song song với backend. Dùng thử Apidog miễn phí để kiểm thử theo hướng dẫn.

API chuyển văn bản thành video của Grok là gì?

API này thuộc bộ công cụ tạo media của xAI tại https://api.x.ai. Bạn gửi prompt dạng text, model grok-imagine-video sẽ tạo video từ đầu (không cần ảnh gốc).

API đồng hành với endpoint tạo ảnh đồng bộ (POST /v1/images/generations, model grok-imagine-image, $0.02/ảnh). Ngoài ra còn có endpoint mở rộng và chỉnh sửa video.

Điểm khác biệt so với chuyển hình ảnh thành video: endpoint chuyển văn bản thành video chỉ cần text, toàn bộ cảnh và chuyển động được model tạo dựa trên mô tả của bạn. Nếu bạn cần hoạt họa từ ảnh gốc, xem hướng dẫn API chuyển hình ảnh thành video của Grok.

Cách hoạt động của tính năng tạo video từ văn bản

Thông thường, API đồng bộ trả về kết quả sau khi xử lý xong. Tuy nhiên, tạo video có thể mất vài giây đến vài phút, nên API này sử dụng mô hình bất đồng bộ.

Luồng thực tế:

1. Gửi POST với prompt.
2. API trả về request_id ngay (dưới 1 giây).
3. Máy chủ xAI xử lý tạo video.
4. Bạn liên tục truy vấn GET với request_id.
5. Khi trạng thái đổi từ "processing" sang "done", phản hồi trả về URL video.

Luồng này giúp giữ cho kết nối HTTP ngắn, chủ động kiểm tra tiến độ. UI cần xử lý trạng thái chờ, hiển thị loading indicator cho tới khi có link video.

Điều kiện tiên quyết

Trước khi code, bạn cần:

• Tài khoản xAI: Đăng ký tại console.x.ai. Thêm thông tin thanh toán để kích hoạt quyền tạo video.
• API Key: Truy cập mục API Keys trong console xAI để tạo key mới. Lưu key an toàn và dùng nó làm Bearer token trong header mỗi request.

Thiết lập biến môi trường:

export XAI_API_KEY="your_api_key_here"

Cài đặt SDK Python (nếu muốn):

pip install xai-sdk

Yêu cầu tạo video từ văn bản đầu tiên

Endpoint: POST https://api.x.ai/v1/videos/generations. Chỉ cần trường model và prompt.

Sử dụng curl

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Một chú chó Golden Retriever chạy qua những chiếc lá mùa thu trong chuyển động chậm, ánh sáng điện ảnh"
  }'

Phản hồi (gần như ngay lập tức):

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

Sử dụng Python với requests

import requests
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "grok-imagine-video",
    "prompt": "Một chú chó Golden Retriever chạy qua những chiếc lá mùa thu trong chuyển động chậm, ánh sáng điện ảnh"
}

response = requests.post(
    f"{BASE_URL}/v1/videos/generations",
    headers=headers,
    json=payload
)

data = response.json()
request_id = data["request_id"]
print(f"Bắt đầu tạo. Request ID: {request_id}")

Truy vấn kết quả video

Sau khi có request_id, truy vấn GET /v1/videos/{request_id} lặp lại cho tới khi status bằng "done".

Các trạng thái:

• processing: đang tạo
• done: hoàn thành, có URL video
• failed: tạo thất bại

Vòng lặp truy vấn trạng thái bằng Python:

import requests
import time
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
    url = f"{BASE_URL}/v1/videos/{request_id}"

    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        data = response.json()

        status = data.get("status")
        progress = data.get("progress", 0)
        print(f"Thử lần {attempt + 1}: status={status}, progress={progress}%")

        if status == "done":
            return data
        elif status == "failed":
            raise RuntimeError(f"Tạo video thất bại: {data}")

        time.sleep(interval)

    raise TimeoutError(f"Video chưa sẵn sàng sau {max_attempts} lần thử")

def generate_video(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/videos/generations",
        headers={**headers, "Content-Type": "application/json"},
        json={"model": "grok-imagine-video", "prompt": prompt}
    )
    request_id = response.json()["request_id"]
    print(f"Request ID: {request_id}")

    result = poll_video(request_id)
    video_url = result["video"]["url"]
    print(f"Video đã sẵn sàng: {video_url}")
    return video_url

video_url = generate_video(
    "Một đoạn thời gian trôi của đường chân trời thành phố lúc hoàng hôn chuyển sang ban đêm, góc nhìn từ trên không"
)

Phản hồi hoàn tất:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}

Sử dụng SDK Python của xAI

SDK tự động xử lý truy vấn trạng thái. Hàm client.video.generate() chờ đến khi video hoàn tất.

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

result = client.video.generate(
    model="grok-imagine-video",
    prompt="Một chú chó Golden Retriever chạy qua những chiếc lá mùa thu trong chuyển động chậm",
    duration=8,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"URL video: {result.video.url}")
print(f"Thời lượng: {result.video.duration}s")

SDK phù hợp khi bạn cần thực thi đơn giản. Nếu muốn kiểm soát logic retry, cập nhật progress hoặc interval truy vấn, dùng phương pháp request thuần.

Viết prompt hiệu quả để tạo video

• Mô tả cảnh: Chủ thể + bối cảnh, càng cụ thể càng tốt.
• Chuyển động: Chỉ ra cái gì di chuyển, hướng, tốc độ.
• Phong cách máy quay: Dùng thuật ngữ điện ảnh: "cận cảnh", "theo dõi", "góc drone", "dolly zoom"...
• Ánh sáng & tâm trạng: "giờ vàng", "u ám", "neon", "sáng studio"... kết hợp mood và lighting.
• Tham chiếu phong cách: Nêu tên style nếu có: "điện ảnh", "anime", "hyperlapse", "stop-motion"...

Mẫu prompt tối ưu:

Một phi hành gia đơn độc trôi qua Trạm Vũ trụ Quốc tế,
dây buộc trôi phía sau họ. Máy quay theo dõi chậm rãi
bên cạnh, hiển thị Trái đất bên dưới. Điện ảnh, chất lượng IMAX,
ánh sáng mặt trời mọc ấm áp phản chiếu trên tấm che mặt.

Kiểm soát độ phân giải, thời lượng và tỷ lệ khung hình

• Thời lượng: 1-15 giây (default: 6). Video dài hơn tốn nhiều chi phí.
• Độ phân giải: "480p" (default, dùng test/dev), "720p" (dùng sản xuất).
• Tỷ lệ khung hình: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3.

Tỷ lệ	Tốt nhất cho
16:9	Desktop, YouTube, trình chiếu
9:16	TikTok, Instagram Reels, mobile
1:1	Instagram feed, social card
4:3	Video cổ điển, trình chiếu
3:4	Nội dung di động dọc
3:2	Ảnh tiêu chuẩn
2:3	Ảnh chân dung

Ví dụ đầy đủ:

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Một thị trấn ven biển lúc bình minh, sóng vỗ nhẹ nhàng vào bờ đá",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Sử dụng hình ảnh tham chiếu để định hướng phong cách video

Dùng trường reference_images (tối đa 7 ảnh, dạng URL) để định hướng visual style và content mà không trở thành subject chính.

{
  "model": "grok-imagine-video",
  "prompt": "Một thị trấn ven biển lúc bình minh, sóng vỗ nhẹ nhàng vào bờ đá",
  "reference_images": [
    {"url": "https://example.com/my-style-reference.jpg"},
    {"url": "https://example.com/color-palette-reference.jpg"}
  ]
}

Chọn bộ ảnh nhất quán về thẩm mỹ, tránh mix quá nhiều style khác nhau.

Khác biệt: Hình ảnh tham chiếu chỉ ảnh hưởng style, không giống endpoint chuyển hình ảnh thành video (ảnh nguồn = frame đầu tiên).

Mở rộng và chỉnh sửa video đã tạo

xAI cung cấp hai endpoint:

• Mở rộng: POST /v1/videos/extensions: Truyền request_id của video gốc + prompt mới để thêm cảnh quay, vượt giới hạn 15s.
• Chỉnh sửa: POST /v1/videos/edits: Thay đổi style, cảnh, hiệu ứng bằng prompt mới.

Cả hai đều trả về request_id, bạn truy vấn như quy trình tạo video chính.

Đọc chi phí từ phản hồi API

Phản hồi chứa trường usage:

"usage": {
  "cost_in_usd_ticks": 500000000
}

Chia cho 10,000,000 để ra USD:

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Chi phí: ${cost_in_usd:.4f}")
# Output: Chi phí: $0.0500

Bảng giá:

Độ phân giải	Giá/giây	Clip 10 giây
480p	$0.05	$0.50
720p	$0.07	$0.70

Theo dõi trường cost_in_usd_ticks để quản lý chi phí và xây dựng dashboard theo dõi sử dụng.

Cách kiểm tra API video Grok với Apidog

Mô hình bất đồng bộ gây khó khăn khi kiểm thử UI: bạn cần kiểm thử cả 3 trạng thái (loading, success, error) mà không tốn chi phí API thực. Smart Mock của Apidog giúp bạn mô phỏng endpoint và lược đồ phản hồi dễ dàng.

Case 1: Smart Mock cho phát triển giao diện

Mô phỏng endpoint tạo video:

• Tạo POST /v1/videos/generations trong Apidog project.
• Lược đồ phản hồi chỉ cần 1 trường string request_id.

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

Mô phỏng endpoint truy vấn trạng thái:

• Tạo GET /v1/videos/{request_id}.
• Lược đồ gồm status, video.url, video.duration, progress, usage.cost_in_usd_ticks.
• Custom mock trả về "status": "done" và URL placeholder.

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/mock-video-12345.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 400000000
  }
}

UI developer có thể test toàn bộ player, trạng thái loading, success, error mà không tốn chi phí API.

Case 2: Kịch bản kiểm thử vòng lặp truy vấn trạng thái

• Bước 1: Thêm yêu cầu POST tạo video. Sau khi gửi, extract request_id bằng JSONPath $.request_id sang biến videoRequestId.
• Bước 2: Thêm GET /v1/videos/{{videoRequestId}} vào vòng lặp For. Thoát khi response.body.status == "done". Thêm wait 5 giây mỗi lượt.
• Bước 3: Assertion kiểm tra $.video.url không rỗng sau khi hoàn tất.

Kịch bản này giúp kiểm thử CI/CD tự động, phát hiện lỗi logic truy vấn bất đồng bộ.

Chuyển văn bản thành video vs chuyển hình ảnh thành video

Cùng dùng model grok-imagine-video nhưng mục đích khác nhau:

• Chuyển văn bản thành video: Khi cần tạo nội dung gốc, không có ảnh nguồn, muốn model tự do sáng tạo.
• Chuyển hình ảnh thành video: Khi có ảnh sản phẩm, artwork, muốn giữ chi tiết gốc, làm animation cho ảnh sẵn có.

Xác định loại đầu vào: nếu có ảnh, dùng POST /v1/images/generations; nếu chỉ có text, dùng POST /v1/videos/generations.

Xem thêm hướng dẫn API chuyển hình ảnh thành video của Grok.

Các lỗi thường gặp và cách khắc phục

• 401 Unauthorized: API key sai/hết hạn. Kiểm tra header Authorization dạng Bearer YOUR_XAI_API_KEY.
• 429 Too Many Requests: Quá giới hạn tốc độ (60 req/phút, 1 req/giây). Chèn delay 5 giây khi polling.
• status: "failed": Prompt bị kiểm duyệt. Kiểm tra trường respect_moderation, sửa prompt cho rõ ràng/hợp lệ.
• URL video 404: Link video hết hạn nhanh. Tải video về ngay sau khi nhận được URL.
• Video trống/đóng băng: Prompt quá mơ hồ, thiếu mô tả chuyển động. Hãy bổ sung chi tiết chuyển động.
• Thời gian truy vấn chậm: Video 720p hoặc dài mất nhiều thời gian hơn. Dùng 480p, thời lượng ngắn khi dev/test.

Kết luận

API chuyển văn bản thành video của Grok đơn giản hóa quy trình: gửi prompt, nhận request_id, truy vấn tới khi xong, lấy file MP4. Hiểu rõ mô hình bất đồng bộ là chìa khóa. Khi đã có vòng lặp truy vấn ổn định, các tham số còn lại (thời lượng, độ phân giải, tỷ lệ, ảnh tham chiếu) rất dễ điều chỉnh.

Triển khai thực tế nên theo dõi chi phí qua cost_in_usd_ticks. Sử dụng Apidog để giả lập endpoint và tạo test scenario, giúp frontend không bị chậm tiến độ chờ backend. Test Scenarios giúp đảm bảo logic truy vấn luôn chuẩn khi tích hợp.

Câu hỏi thường gặp

Tôi sử dụng tên mô hình nào để tạo video từ văn bản?

Dùng grok-imagine-video làm trường model trong POST /v1/videos/generations.

Tạo video mất bao lâu?

Tùy thời lượng/độ phân giải. Clip 480p ngắn: <30 giây; 720p dài: vài phút. Poll mỗi 5-10 giây.

Có thể tạo video dài hơn 15 giây không?

Không thể trong một request. Dùng POST /v1/videos/extensions để nối thêm.

Làm sao tải video đã tạo?

Dùng URL từ result.video.url khi truy vấn xong, tải về ngay vì link sẽ hết hạn.

Nếu prompt bị kiểm duyệt thì sao?

Job trả về status: "failed", trường respect_moderation: true. Sửa prompt và thử lại.

API video có free tier không?

xAI tính phí theo số giây video. Không có free tier riêng cho video, nhưng có thể có credit cho tài khoản mới (xem tại console.x.ai).

reference_images khác gì với ảnh nguồn?

Ảnh tham chiếu chỉ định hướng style cho chuyển văn bản thành video, không phải khung hình đầu. Ảnh nguồn dùng cho chuyển hình ảnh thành video sẽ là frame đầu tiên.

Cách kiểm thử vòng lặp truy vấn tiết kiệm nhất?

Dùng Smart Mock của Apidog để mô phỏng cả endpoint tạo video lẫn truy vấn trạng thái, định nghĩa schema và response cho "processing" và "done", giúp code truy vấn hoạt động mà không tốn chi phí API thực.