Thanawat Wongchai

Posted on Apr 3 • Originally published at apidog.com

วิธีใช้ Grok Text to Video API ฉบับสมบูรณ์

สรุปสั้นๆ

Grok text-to-video API สร้างวิดีโอจากข้อความ prompt ด้วยการเรียก POST /v1/videos/generations จะได้รับ request_id กลับมาทันที แล้วใช้ GET /v1/videos/{request_id} ตรวจสอบสถานะจนกว่าจะเป็น "done" โมเดลคือ grok-imagine-video เริ่มต้น $0.05/วินาที (480p) xAI Python SDK ช่วยทำ polling อัตโนมัติ

ทดลองใช้ Apidog วันนี้

บทนำ

xAI สร้างวิดีโอ 1.2 พันล้านรายการในเดือนแรกหลังเปิดตัว Grok text-to-video API (28 มกราคม 2026) โมเดลนี้ติดอันดับหนึ่ง text-to-video ของ Artificial Analysis ในเดือนเดียวกัน โครงสร้างพื้นฐานรองรับปริมาณงานขนาดใหญ่แล้ว

คู่มือนี้ให้ขั้นตอนตั้งแต่สร้างคำขอแรก, ตรวจสอบผลลัพธ์, ปรับแต่งพารามิเตอร์, เขียน prompt ให้ดีขึ้น, ใช้รูปภาพอ้างอิง, ขยาย/แก้ไขวิดีโอ และเลือก text-to-video ให้เหมาะกับงานของคุณ

💡 API ทำงาน async: ส่วนหน้า (frontend) ไม่สามารถรอให้วิดีโอพร้อมก่อนแสดงผล คุณต้องใช้ polling flow เสมอ Smart Mock ของ Apidog ช่วยสร้าง mock endpoint ทั้ง generation และ polling เพื่อให้ dev frontend พัฒนา UI ได้แม้ backend ยังไม่เสร็จ ดาวน์โหลด Apidog ฟรีเพื่อทดสอบตามคู่มือนี้

Grok text-to-video API คืออะไร?

Grok text-to-video API อยู่ที่ https://api.x.ai ส่งข้อความ prompt แล้วโมเดล grok-imagine-video จะสร้างคลิปวิดีโอใหม่โดยไม่ต้องมีภาพต้นฉบับ

API ตัวนี้ทำงานร่วมกับ endpoint สร้างรูปภาพแบบ synchronous (POST /v1/images/generations, โมเดล grok-imagine-image, $0.02/ภาพ) และ endpoint ขยาย/แก้ไขวิดีโอ

text-to-video: ให้แค่ข้อความ prompt โมเดลสร้างฉาก, motion, สไตล์เอง
image-to-video: ให้รูปต้นฉบับ โมเดลทำให้ภาพนั้นเคลื่อนไหว

ดู คู่มือ Grok image-to-video API ถ้าคุณต้องการให้ภาพนิ่งเคลื่อนไหว

การสร้างวิดีโอจากข้อความ (async flow)

การสร้างวิดีโอใช้เวลาหลายวินาทีถึงนาที API จึงเป็น async:

ส่ง POST พร้อม prompt
ได้ request_id ทันที
วิดีโอถูกสร้างบนเซิร์ฟเวอร์
Poll ที่ GET endpoint ด้วย request_id
ได้ status เปลี่ยนเป็น "done" จะได้ URL วิดีโอ

หมายเหตุ: frontend ต้องแสดง loading state ระหว่างรอ

ข้อกำหนดเบื้องต้น

บัญชี xAI: สมัครที่ console.x.ai ต้องกรอกข้อมูล billing ก่อนสร้าง video ได้
API key: สร้างที่ API Keys ในคอนโซล xAI ส่งเป็น Bearer token ทุก request

ตั้งค่าเป็น env variable:

export XAI_API_KEY="your_api_key_here"

(เลือก) ติดตั้ง xAI Python SDK:

pip install xai-sdk

คำขอ text-to-video แรกของคุณ

Endpoint: POST https://api.x.ai/v1/videos/generations

จำเป็น: model, prompt

ตัวอย่าง 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": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
  }'

ผลลัพธ์:

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

ตัวอย่าง Python (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": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}

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

data = response.json()
request_id = data["request_id"]
print(f"Generation started. Request ID: {request_id}")

การตรวจสอบสถานะเพื่อรับผลลัพธ์วิดีโอ

เมื่อต้องการผลลัพธ์ ให้เรียก GET /v1/videos/{request_id} เรื่อยๆ จน status เป็น "done"

status ที่เป็นไปได้:

"processing": กำลังสร้าง
"done": เสร็จ มี URL วิดีโอ
"failed": ล้มเหลว

Polling Loop (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"Attempt {attempt + 1}: status={status}, progress={progress}%")
        if status == "done":
            return data
        elif status == "failed":
            raise RuntimeError(f"Video generation failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Video not ready after {max_attempts} attempts")

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 ready: {video_url}")
    return video_url

video_url = generate_video(
    "A timelapse of a city skyline at sunset transitioning to night, aerial view"
)

ตัวอย่างผลลัพธ์เมื่อ status = done:

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

การใช้ xAI Python SDK

SDK จะ handle polling ให้อัตโนมัติ:

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="A golden retriever running through autumn leaves in slow motion",
    duration=8,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {result.video.url}")
print(f"Duration: {result.video.duration}s")

ใช้ SDK สำหรับการพัฒนาเร็ว ถ้าต้องการควบคุม retry หรือ polling interval ใช้ raw HTTP

การเขียน prompt ที่มีประสิทธิภาพสำหรับวิดีโอ

อธิบายฉากชัดเจน: บอกตัวแบบ+ฉากหลัง
การเคลื่อนไหว: เจาะจงว่ากล้องหรือ object เคลื่อนไหวยังไง
สไตล์กล้อง: เช่น "close-up", "drone shot"
แสง/บรรยากาศ: "golden hour", "overcast", ฯลฯ
อ้างอิงสไตล์: "cinematic", "anime", ผสมหลายสไตล์ได้
prompt โครงสร้างดี:

  A lone astronaut floats past the International Space Station,
  tether drifting behind them. The camera tracks slowly
  alongside, showing Earth below. Cinematic, IMAX quality,
  warm sunrise light reflecting off the visor.

การควบคุมความละเอียด, ระยะเวลา, อัตราส่วนภาพ

duration: 1-15 วินาที (default 6s)
resolution: "480p" (default), "720p"
aspect_ratio: "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3"

อัตราส่วน	เหมาะสำหรับ
16:9	เดสก์ท็อป, YouTube (default)
9:16	TikTok, IG Reels, มือถือ
1:1	IG feed, social cards
4:3	วิดีโอคลาสสิก, นำเสนอ
3:4	มือถือแนวตั้ง
3:2	ภาพถ่ายมาตรฐาน
2:3	ถ่ายภาพบุคคล

ตัวอย่าง 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": "A coastal town at dawn, waves breaking gently on a rocky shore",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

การใช้รูปภาพอ้างอิงเพื่อกำหนดสไตล์วิดีโอ

ส่ง reference_images (array URLs สูงสุด 7 ภาพ) เพื่อชี้นำสไตล์และโทนภาพ:

{
  "model": "grok-imagine-video",
  "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
  "reference_images": [
    {"url": "https://example.com/my-style-reference.jpg"},
    {"url": "https://example.com/color-palette-reference.jpg"}
  ]
}

ภาพควรสอดคล้องกันเพื่อผลลัพธ์ดีที่สุด
ต่างจาก image-to-video: prompt ยังขับเคลื่อนฉากหลัก

การขยายและแก้ไขวิดีโอที่สร้างขึ้น

ขยายวิดีโอ: POST /v1/videos/extensions ส่ง request_id + prompt ใหม่ เพื่อเพิ่มฟุตเทจต่อท้าย (ใช้ทำคลิปยาว >15 วินาที)
แก้ไขวิดีโอ: POST /v1/videos/edits ส่ง request_id + prompt เพื่อเปลี่ยนสไตล์/ฉาก/เอฟเฟกต์

ทั้งคู่ใช้ polling แบบเดียวกับ main endpoint

การอ่านค่าใช้จ่ายจาก API

ผลลัพธ์ที่สมบูรณ์จะมี usage:

"usage": {
  "cost_in_usd_ticks": 500000000
}

หารด้วย 10,000,000 เพื่อแปลงเป็นดอลลาร์:

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

ตารางราคา

ความละเอียด	ราคาต่อวินาที	คลิป 10 วินาที
480p	$0.05	$0.50
720p	$0.07	$0.70

บันทึก cost_in_usd_ticks จากทุก polling ที่สำเร็จเพื่อ track ต้นทุน

วิธีทดสอบ Grok video API ของคุณด้วย Apidog

async polling flow ทำให้ทดสอบ frontend ยาก เพราะต้อง handle สถานะ loading/success/error โดยไม่เปลืองเครดิตจริง Smart Mock ของ Apidog ช่วยแก้ปัญหานี้

กรณี 1: Smart Mock สำหรับ dev frontend

จำลอง generation endpoint:
- สร้าง POST /v1/videos/generations กำหนด response schema มี request_id
- Smart Mock ตอบกลับ UUID ปลอม
- ตัวอย่าง:
```
{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
```

จำลอง poll endpoint:

สร้าง GET /v1/videos/{request_id} กำหนด response schema เต็ม
ตั้ง Custom Mock response ส่ง "status": "done" + URL วิดีโอเทียม

{
  "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
  }
}

Dev frontend สามารถสร้าง UI player, ทดสอบ loading/success/fail ได้โดยไม่เปลืองเครดิต

กรณี 2: Test Scenario สำหรับ polling loop

Step 1: สร้าง POST /v1/videos/generations ดึง request_id ด้วย JSONPath $.request_id เก็บในตัวแปร
Step 2: สร้าง GET /v1/videos/{{videoRequestId}} ห่อด้วย for loop (หยุดเมื่อ status=="done") ใส่ wait 5 วินาที
Step 3: Assertion $.video.url ต้องไม่ว่าง

รันใน CI เพื่อจับ bug polling logic ได้อัตโนมัติ

Text-to-video vs image-to-video: เลือกใช้อย่างไร

text-to-video: สร้างฉากใหม่จาก prompt เหมาะกับเนื้อหาต้นฉบับ/ไม่มีรูปภาพ
image-to-video: เคลื่อนไหวรูปภาพที่มี เหมาะกับ assets, แบรนด์ หรือภาพวาด

ดู คู่มือ Grok image-to-video API สำหรับรายละเอียด

ตรวจจับ input: ถ้ามีภาพ ส่ง image-to-video, ถ้าไม่มี ส่ง text-to-video

ข้อผิดพลาดที่พบบ่อยและวิธีแก้ไข

401 Unauthorized: ตรวจสอบ API Key, header, คีย์หมดอายุหรือไม่
429 Too Many Requests: เกิน rate limit (60/min, 1/sec) เพิ่มดีเลย์ตรวจสอบสถานะอย่างน้อย 5s
status: "failed": Prompt โดน content moderation, ปรับแก้ prompt ใหม่
URL วิดีโอ 404: URL หมดอายุ ดาวน์โหลดทันทีหลังได้ URL
วิดีโอว่าง/ค้าง: Prompt คลุมเครือหรือไม่มี motion, เพิ่มคำอธิบายการเคลื่อนไหว
รอตรวจสอบสถานะนาน: 720p/คลิปยาวใช้เวลาสร้างนาน ใช้ 480p + สั้นๆ สำหรับ prototype

บทสรุป

Grok text-to-video API ใช้งานตรงไปตรงมา: ส่ง prompt, ได้ request_id, poll จน "done", โหลด MP4

เน้นเข้าใจ async flow (polling) ก่อน ส่วนพารามิเตอร์อื่นๆ เช่น ระยะเวลา, ความละเอียด, อัตราส่วน, รูปภาพอ้างอิง สามารถปรับแต่งได้ง่าย

ติดตามค่าใช้จ่ายด้วย cost_in_usd_ticks
จำลอง endpoint ทั้งสองใน Apidog เพื่อให้ dev frontend ทำงานได้เร็ว
ใช้ Test Scenarios ตรวจสอบ polling logic ได้อัตโนมัติ

ดาวน์โหลด Apidog ฟรีเพื่อตั้งค่า mock server และ test scenarios สำหรับ Grok video API ของคุณ

คำถามที่พบบ่อย

Q: ใช้ชื่อโมเดลอะไรสร้างวิดีโอจากข้อความ?

A: ใช้ "grok-imagine-video" ใส่ในฟิลด์ model ขณะ POST /v1/videos/generations

Q: สร้างวิดีโอนานแค่ไหน?

A: แล้วแต่ duration/resolution 480p สั้นๆ ประมาณ 30 วินาที, 720p ยาวๆ หลายนาที Poll ทุก 5-10 วินาที

Q: สร้างวิดีโอยาวเกิน 15 วินาทีได้ไหม?

A: ไม่ได้ในการเรียกเดียว (duration สูงสุด 15s) ใช้ POST /v1/videos/extensions ต่อฟุตเทจ

Q: ดาวน์โหลดวิดีโอที่สร้างได้อย่างไร?

A: ใช้ URL จาก result.video.url ใน polling ที่ status = done โหลดทันที URL จะหมดอายุ

Q: ถ้า prompt โดน moderation?

A: status จะเป็น "failed" ฟิลด์ respect_moderation = true ให้แก้ prompt แล้วลองใหม่

Q: มีบริการฟรีสำหรับ video API ไหม?

A: ไม่มีฟรี xAI คิดค่าบริการตามวินาที ดูข้อเสนอเครดิตใน console.x.ai

Q: reference_images ต่างจาก image-to-video ยังไง?

A: reference_images ช่วยชี้นำสไตล์เท่านั้น ไม่กลายเป็นตัวแบบ ส่วน image-to-video รูปภาพต้นฉบับคือเฟรมแรกจริง

Q: ทดสอบ polling loop โดยไม่เสียเครดิตยังไง?

A: ใช้ Smart Mock ของ Apidog จำลองทั้ง generation/poll endpoint ได้ครบทุกสถานะ

DEV Community