Cara Menggunakan Grok Text to Video API (Panduan Lengkap)

Ringkasan

API Grok text-to-video menghasilkan video dari sebuah prompt teks. Anda memanggil POST /v1/videos/generations, segera mendapatkan request_id kembali, lalu melakukan polling GET /v1/videos/{request_id} hingga statusnya "done". Modelnya adalah grok-imagine-video, harga mulai dari $0.05 per detik pada resolusi 480p. xAI Python SDK menangani polling secara otomatis.

Pendahuluan

xAI menghasilkan 1,2 miliar video hanya pada Januari 2026. Itu adalah bulan pertama setelah meluncurkan API Grok text-to-video pada 28 Januari 2026. Model ini juga menduduki peringkat nomor satu di papan peringkat text-to-video Artificial Analysis pada bulan yang sama. Angka-angka tersebut penting karena menunjukkan bahwa infrastrukturnya telah terbukti dalam skala besar.

Panduan ini memandu Anda melalui setiap langkah: membuat permintaan pertama Anda, melakukan polling untuk hasilnya, menyesuaikan parameter, dan menulis prompt yang lebih baik. Anda juga akan belajar cara menggunakan gambar referensi, memperpanjang atau mengedit video yang ada, dan memahami kapan text-to-video adalah pilihan yang tepat.

button

Apa itu API Grok text to video?

API Grok text-to-video adalah bagian dari suite pembuatan media xAI di https://api.x.ai. Anda mengirimkan prompt teks dan model grok-imagine-video menghasilkan klip video pendek dari awal. Tidak diperlukan gambar sumber.

API ini bersanding dengan endpoint pembuatan gambar sinkron (POST /v1/images/generations, model grok-imagine-image, $0.02 per gambar). Ini juga mencakup endpoint untuk memperpanjang atau mengedit video.

Endpoint text-to-video berbeda dari endpoint image-to-video secara fundamental: Anda hanya menyediakan kata-kata. Model menciptakan adegan, gerakan, dan gaya visual sepenuhnya dari deskripsi Anda. Lihat panduan API Grok image to video jika Anda memiliki gambar sumber dan ingin model menganimasikannya.

Cara kerja pembuatan text-to-video (pola async dijelaskan secara sederhana)

Sebagian besar panggilan API bersifat sinkron. Anda mengirim permintaan, menunggu sebentar, mendapatkan respons Anda. Pembuatan video membutuhkan waktu detik hingga menit, jadi API menggunakan pola async sebagai gantinya.

Berikut alurnya:

1. Anda mengirim permintaan POST dengan prompt Anda.
2. API segera mengembalikan request_id (dalam waktu kurang dari satu detik).
3. Video sedang dibuat di server xAI.
4. Anda melakukan polling ke endpoint GET dengan request_id tersebut berulang kali.
5. Ketika status berubah dari "processing" menjadi "done", responsnya mencakup URL video.

Pola ini umum dalam API media AI. Ini menjaga koneksi HTTP Anda tetap singkat dan memungkinkan Anda memeriksa kemajuan sesuai keinginan Anda. Bagian yang sulit adalah frontend Anda perlu menangani status menengah, menampilkan indikator pemuatan sampai URL video tiba.

Prasyarat

Sebelum Anda menulis kode apa pun, Anda memerlukan dua hal:

Akun xAI. Buat satu di console.x.ai. Anda juga akan menambahkan penagihan di sana sebelum kunci API Anda memiliki akses pembuatan.

Kunci API. Di konsol xAI, navigasikan ke API Keys dan buat kunci baru. Salin di tempat yang aman. Anda akan meneruskannya sebagai token Bearer di setiap header permintaan.

Atur sebagai variabel lingkungan agar Anda tidak menuliskannya secara hardcode:

export XAI_API_KEY="your_api_key_here"

Secara opsional, instal xAI Python SDK untuk integrasi paling sederhana:

pip install xai-sdk

Permintaan text-to-video pertama Anda

Endpointnya adalah POST https://api.x.ai/v1/videos/generations. Bidang yang wajib diisi hanyalah model dan prompt.

Menggunakan 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"
  }'

Respons akan segera kembali:

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

UUID itu adalah tiket Anda untuk mengambil video setelah siap.

Menggunakan Python dengan pustaka 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}")

Polling untuk hasil video

Setelah Anda memiliki request_id, lakukan polling GET /v1/videos/{request_id} hingga kolom status sama dengan "done".

Kolom status memiliki tiga nilai yang mungkin: - "processing": masih dalam proses pembuatan - "done": selesai, URL video tersedia - "failed": terjadi kesalahan

Berikut adalah loop polling Python yang lengkap:

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:
    """Poll until video generation is complete."""
    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")


# Full workflow: generate then poll
def generate_video(prompt: str) -> str:
    """Generate a video and return its URL."""
    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"
)

Setelah selesai, respons polling lengkap terlihat seperti ini:

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

Menggunakan xAI Python SDK

Jika Anda lebih suka melewati polling manual, xAI SDK menanganinya untuk Anda. Metode client.video.generate() akan memblokir hingga video siap.

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 adalah jalur tercepat menuju kode yang berfungsi. Gunakan pendekatan permintaan mentah (raw requests) ketika Anda membutuhkan lebih banyak kontrol atas logika percobaan ulang, pembaruan kemajuan, atau interval polling kustom.

Menulis prompt yang efektif untuk pembuatan video

Prompt Anda adalah masukan terpenting. Prompt yang terperinci dan terstruktur menghasilkan hasil yang jauh lebih baik daripada yang samar-samar.

Deskripsi adegan

Jelaskan subjek dan latar bersama-sama. Spesifikkan apa yang terlihat. "Cangkir kopi keramik putih di atas meja kayu di samping jendela yang basah karena hujan" menghasilkan adegan yang lebih membumi daripada "sebuah cangkir kopi."

Gerakan

Beritahu model apa yang bergerak dan bagaimana. "Kamera perlahan mengitari cangkir saat uap mengepul ke atas" menambahkan gerakan dengan arah yang jelas. Tanpa isyarat gerakan eksplisit, model mungkin menghasilkan gerakan minimal atau mengganggu.

Gaya kamera

Gunakan terminologi kamera yang akan Anda berikan kepada sinematografer: "close-up," "tracking shot," "overhead drone view," "handheld," "dolly zoom." Isyarat-isyarat ini secara andal diterjemahkan ke dalam rekaman yang dihasilkan.

Pencahayaan dan suasana hati

"Golden hour," "overcast," "neon-lit," dan "studio three-point lighting" semuanya menghasilkan tampilan yang berbeda. Pasangkan pencahayaan dengan suasana hati: "pagi berkabut, suasana melankolis" memberikan model panduan nada di luar suhu warna.

Referensi gaya

Sebutkan gaya visual jika Anda memilikinya: "sinematik," "dokumenter," "anime," "stop-motion," "hyperlapse." Menggabungkan dua gaya seringkali menghasilkan hasil yang menarik.

Struktur prompt yang berhasil

Mulai dengan subjek, tambahkan gerakan, jelaskan kamera, akhiri dengan gaya dan suasana hati. Seperti ini:

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.

Mengontrol resolusi, durasi, dan rasio aspek

Endpoint pembuatan menerima beberapa parameter opsional yang memungkinkan Anda mengontrol dimensi keluaran, panjang, dan kualitas.

Durasi

"duration": 10

Rentang: 1 hingga 15 detik. Default adalah 6 detik. Video yang lebih panjang biayanya lebih mahal. Klip 10 detik pada 480p berharga $0.50.

Resolusi

"resolution": "720p"

Dua pilihan: "480p" (default) dan "720p". Gunakan 480p untuk prototipe dan pengujian. Gunakan 720p untuk keluaran produksi di mana kualitas menjadi penting.

Rasio aspek

"aspect_ratio": "9:16"

Rasio yang tersedia:

Contoh lengkap dengan semua parameter

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

Menggunakan gambar referensi untuk memandu gaya video

Parameter reference_images menerima sebuah array hingga 7 URL gambar. Gambar-gambar ini memandu gaya visual dan konten video yang dihasilkan tanpa menjadi subjeknya.

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

Gambar referensi berfungsi paling baik jika memiliki estetika yang konsisten. Jika Anda memberikan tiga gambar dari gaya visual yang berbeda, model mencoba untuk menyatukannya dan hasilnya mungkin terlihat tidak konsisten. Gunakan kumpulan gambar yang ketat dengan tampilan terpadu untuk panduan terkuat.

Gambar referensi berbeda dari endpoint image-to-video. Dengan gambar referensi, prompt Anda masih menggerakkan adegan. Gambar-gambar tersebut memengaruhi grading warna, gaya komposisi, dan tekstur visual. Dengan image-to-video, gambar sumber menjadi bingkai pertama.

Memperpanjang dan mengedit video yang dihasilkan

xAI menyediakan dua endpoint tambahan untuk bekerja dengan video yang telah Anda hasilkan.

Memperpanjang video

POST /v1/videos/extensions menambahkan lebih banyak rekaman ke video yang sudah ada. Anda meneruskan request_id dari video asli dan prompt baru untuk ekstensi. Ini berguna untuk membuat urutan yang lebih panjang tanpa mencapai batas 15 detik dalam satu panggilan.

Mengedit video

POST /v1/videos/edits memodifikasi video yang sudah ada berdasarkan instruksi teks. Anda dapat mengubah gaya, mengubah adegan, atau menerapkan efek pada klip yang telah Anda hasilkan.

Kedua endpoint mengikuti pola async yang sama dengan endpoint pembuatan utama. Mereka mengembalikan request_id dan Anda melakukan polling GET /v1/videos/{request_id} untuk hasilnya.

Membaca biaya dari respons API

Respons polling yang selesai mencakup objek usage:

"usage": {
  "cost_in_usd_ticks": 500000000
}

Unitnya adalah USD ticks. Bagi dengan 10.000.000 untuk mengonversi ke dolar.

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

Referensi harga

Nilai 500000000 tick sama dengan $0.50. Itu adalah klip 10 detik pada resolusi 480p.

Lacak biaya Anda dengan mencatat cost_in_usd_ticks dari setiap respons yang selesai. Ini memungkinkan Anda membangun dasbor penggunaan tanpa memanggil API penagihan xAI secara terpisah.

Cara menguji API video Grok Anda dengan Apidog

Pola polling async menciptakan tantangan pengujian khusus. Kode frontend Anda perlu menangani tiga status: memuat (saat polling), sukses (URL video diterima), dan error. Anda tidak dapat menguji ketiga status ini dengan melakukan panggilan API sungguhan, karena setiap panggilan membutuhkan waktu dan biaya. Di sinilah fitur Smart Mock Apidog menyelesaikan masalah secara langsung.

Kasus penggunaan 1: Smart Mock untuk pengembangan frontend

Dengan Smart Mock Apidog, Anda menentukan skema untuk kedua endpoint dan Apidog segera mengembalikan respons palsu yang realistis.

Mock endpoint pembuatan:

Di Apidog, buat endpoint POST /v1/videos/generations di proyek Anda. Definisikan skema respons dengan satu kolom string request_id. Smart Mock akan mengembalikan UUID palsu secara otomatis berdasarkan pola nama kolom.

Respons mock Anda:

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

Mock endpoint polling:

Buat GET /v1/videos/{request_id} di Apidog. Definisikan skema respons lengkap termasuk status, video.url, video.duration, progress, dan usage.cost_in_usd_ticks. Atur respons Custom Mock yang mengembalikan "status": "done" dengan URL MP4 placeholder.

Respons polling mock Anda:

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

Pengembang frontend sekarang dapat membangun dan menguji seluruh UI pemutar video terhadap server mock ini. Mereka melihat status pemuatan, status selesai, dan dapat memicu status error dengan memodifikasi mock untuk mengembalikan "status": "failed". Tidak ada kredit API sungguhan yang dihabiskan selama pengembangan.

Kasus penggunaan 2: Skenario Pengujian untuk loop polling

Setelah integrasi Anda dibangun, gunakan Skenario Pengujian Apidog untuk memvalidasi alur generate-lalu-poll secara otomatis.

Langkah 1: Tambahkan permintaan pembuatan. Tambahkan POST /v1/videos/generations sebagai langkah pertama dalam skenario pengujian Anda. Di post-processor, tambahkan Ekstrak Variabel untuk menangkap request_id dari badan respons menggunakan ekspresi JSONPath $.request_id. Simpan dalam variabel bernama videoRequestId.

Langkah 2: Tambahkan loop polling. Tambahkan GET /v1/videos/{{videoRequestId}} sebagai langkah kedua. Bungkus dalam loop For dengan kondisi berhenti: response.body.status == "done". Tambahkan prosesor Tunggu (Wait processor) selama 5 detik di antara iterasi untuk menghindari pemakaian batas kecepatan (rate limit) yang berlebihan.

Langkah 3: Pastikan hasilnya. Setelah loop selesai, tambahkan prosesor Assert (Pernyataan) ke permintaan GET terakhir. Pastikan bahwa $.video.url tidak kosong. Ini menegaskan bahwa siklus penuh berhasil diselesaikan.

Skenario pengujian ini memberi Anda cakupan otomatis yang berulang untuk alur async. Jalankan di CI untuk menangkap regresi apa pun saat logika polling Anda berubah.

Text-to-video vs image-to-video: kapan menggunakannya

Kedua mode menggunakan model grok-imagine-video yang sama, tetapi melayani tujuan yang berbeda.

Pilih text-to-video saat:- Anda membuat konten asli dari konsep atau skrip - Anda ingin model memiliki kontrol kreatif penuh atas komposisi - Anda membangun alat pembuatan konten tempat pengguna mengetik prompt - Anda tidak memiliki gambar sumber untuk memulai

Pilih image-to-video saat:- Anda memiliki foto produk, ilustrasi, atau aset merek untuk dianimasikan - Anda perlu mempertahankan detail visual tertentu dari gambar yang sudah ada - Anda membuat animasi yang konsisten dari serangkaian gambar terkait - Anda ingin menganimasikan karya seni atau fotografi Anda sendiri

Perbedaan utamanya: text-to-video menciptakan adegan dari awal. Image-to-video membuat gambar yang sudah ada bergerak. Untuk panduan lengkap tentang pendekatan image-to-video, lihat panduan API Grok image to video.

Untuk tim yang membangun produk yang menawarkan kedua mode, Anda dapat mendeteksi jenis masukan saat runtime. Jika pengguna mengunggah gambar, arahkan ke POST /v1/images/generations (image-to-video). Jika mereka hanya mengetik prompt, arahkan ke POST /v1/videos/generations.

Kesalahan umum dan cara memperbaikinya

401 Tidak SahKunci API Anda hilang, kedaluwarsa, atau formatnya salah. Pastikan header Otorisasi persis Bearer YOUR_XAI_API_KEY tanpa spasi tambahan. Konfirmasi bahwa kunci aktif di konsol xAI.

429 Terlalu Banyak PermintaanAnda telah mencapai batas kecepatan. API mengizinkan 60 permintaan per menit dan 1 permintaan per detik. Tambahkan penundaan di antara permintaan. Jika Anda melakukan polling, berikan jarak panggilan Anda setidaknya 5 detik.

status: "failed" dalam respons pollingPembuatan gagal. Ini biasanya berarti prompt ditolak oleh moderasi konten. Kolom respect_moderation dalam respons polling menunjukkan bahwa moderasi diterapkan. Revisi prompt Anda agar tidak ambigu atau hapus bahasa yang berpotensi sensitif.

URL video mengembalikan 404URL video yang dihasilkan akan kedaluwarsa setelah jangka waktu tertentu. Unduh video ke penyimpanan Anda sendiri segera setelah mengambil URL. Jangan menyimpan URL dan mengandalkannya akan tersedia beberapa hari kemudian.

Video kosong atau bekuPrompt yang samar atau prompt tanpa isyarat gerakan kadang-kadang menghasilkan video dengan gerakan minimal. Tambahkan bahasa gerakan eksplisit ke prompt Anda: jelaskan apa yang bergerak, ke arah mana, dan dengan kecepatan berapa.

Waktu polling yang lambatVideo 720p membutuhkan waktu lebih lama untuk dibuat daripada 480p. Durasi yang lebih panjang juga membutuhkan lebih banyak waktu. Untuk pengembangan dan prototipe, gunakan "resolution": "480p" dan durasi pendek untuk mempercepat siklus iterasi.

Kesimpulan

API Grok text-to-video memberi Anda jalur yang mudah dari teks ke video. Anda mengirimkan prompt, mendapatkan request_id, melakukan polling hingga selesai, dan mengambil MP4 Anda. Pola async adalah konsep kunci yang harus dipahami. Setelah loop polling berfungsi, parameter lainnya (durasi, resolusi, rasio aspek, gambar referensi) mudah disesuaikan.

Untuk build produksi, tambahkan pelacakan biaya dengan membaca cost_in_usd_ticks dari setiap respons yang selesai. Palsukan (mock) kedua endpoint di Apidog selama pengembangan agar tim frontend Anda tidak terhambat menunggu pembuatan sungguhan. Gunakan Skenario Pengujian untuk menjaga logika polling Anda tetap andal seiring evolusi integrasi Anda.

Unduh Apidog gratis untuk menyiapkan server mock dan skenario pengujian Anda untuk API video Grok.

button

FAQ

Nama model apa yang saya gunakan untuk pembuatan text-to-video?Gunakan grok-imagine-video. Ini adalah kolom model yang wajib diisi dalam permintaan POST Anda ke /v1/videos/generations.

Berapa lama waktu yang dibutuhkan untuk pembuatan video?Ini bervariasi berdasarkan durasi dan resolusi. Klip pendek 480p mungkin selesai dalam waktu kurang dari 30 detik. Klip 720p yang lebih panjang dapat memakan waktu beberapa menit. Lakukan polling setiap 5-10 detik daripada membanjiri endpoint terus-menerus.

Bisakah saya membuat video lebih dari 15 detik?Tidak dalam satu permintaan tunggal. duration maksimum adalah 15 detik. Untuk membuat video yang lebih panjang, buat klip dan kemudian gunakan POST /v1/videos/extensions untuk menambahkan lebih banyak rekaman.

Bagaimana cara mengunduh video yang dihasilkan?Gunakan URL dari result.video.url dalam respons polling yang selesai. Unduh MP4 ke penyimpanan Anda segera. URL bersifat sementara dan akan kedaluwarsa.

Apa yang terjadi jika prompt saya melanggar moderasi konten?Tugas akan selesai tetapi status akan menjadi "failed". Kolom respect_moderation dalam respons polling menunjukkan bahwa moderasi diterapkan. Revisi prompt Anda dan coba lagi.

Apakah ada tingkat gratis untuk API video?xAI mengenakan biaya per detik keluaran yang dihasilkan. Tidak ada tingkat gratis khusus untuk pembuatan video. Periksa console.x.ai untuk penawaran kredit saat ini untuk akun baru.

Bagaimana reference_images berbeda dari memulai dengan gambar sumber?Gambar referensi memandu gaya visual pembuatan text-to-video. Mereka memengaruhi tampilan tanpa menjadi subjek. Gambar sumber untuk image-to-video menjadi bingkai pertama video yang sebenarnya.

Apa cara terbaik untuk menguji loop polling tanpa menghabiskan kredit?Gunakan Smart Mock Apidog untuk memalsukan (mock) endpoint pembuatan dan polling. Definisikan skema, atur respons mock untuk status "processing" dan "done", dan kode polling Anda akan berfungsi tanpa menyentuh API sungguhan.