Cara Menggunakan API Grok Image ke Video: Panduan Lengkap Langkah demi Langkah

TL;DR

API Grok image-to-video menggunakan model grok-imagine-video untuk menganimasikan gambar statis menjadi klip video. Anda melakukan POST URL gambar Anda, sebuah prompt, dan pengaturan opsional ke https://api.x.ai/v1/videos/generations. API akan segera mengembalikan request_id. Anda kemudian melakukan polling GET /v1/videos/{request_id} hingga status menjadi "done". Durasi berkisar antara 1 hingga 15 detik. Harga mulai dari $0.05 per detik untuk output 480p.

Pengantar

Pada tanggal 28 Januari 2026, xAI meluncurkan model grok-imagine-video untuk akses API publik. Dalam bulan pertama itu, model ini menghasilkan 1,2 miliar video dan menempati peringkat nomor satu di papan peringkat text-to-video Artificial Analysis. Image-to-video adalah salah satu kemampuan utamanya: Anda memberikan foto dan prompt deskriptif kepada API, dan API akan menganimasikan foto tersebut menjadi klip video pendek yang siap diunduh sebagai MP4.

Alur asinkron itu, di mana Anda mengirimkan pekerjaan dan kemudian melakukan polling untuk penyelesaian, memperkenalkan tantangan pengujian yang sering dilewatkan banyak pengembang. Integrasi Anda belum selesai ketika POST pertama mengembalikan 200. Integrasi selesai ketika Anda telah mengkonfirmasi bahwa loop polling menangani status "processing", "done", dan "failed" dengan benar di bawah kondisi jaringan yang nyata.

Skenario Uji Apidog menyelesaikan masalah ini secara langsung. Anda dapat membangun urutan berantai: melakukan post ke /v1/videos/generations, mengekstrak request_id, mengulang permintaan polling hingga status == "done", kemudian menegaskan bahwa URL video sudah ada. Unduh Apidog secara gratis untuk mengikuti panduan pengujian nanti dalam panduan ini.

button

Apa itu API Grok image-to-video?

API Grok image-to-video adalah bagian dari produk generasi video xAI. Ini beroperasi di bawah model grok-imagine-video dan menerima gambar sebagai bingkai awal video output. Model ini mempelajari konten gambar dan prompt teks, kemudian menghasilkan gerakan alami untuk menganimasikan adegan tersebut.

Endpoint API adalah:

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

Autentikasi menggunakan token Bearer standar:

Authorization: Bearer YOUR_XAI_API_KEY

Anda mendapatkan kunci Anda dari konsol xAI. Antarmuka API yang sama juga mendukung text-to-video (hilangkan parameter image), ekstensi video, dan pengeditan video.

Bagaimana cara kerja proses image-to-video

Parameter image dalam badan permintaan menetapkan bingkai pertama dari video output. Model tidak mengganti gambar. Ia memulai dari gambar tersebut. Setiap piksel dalam bingkai pertama berasal dari gambar sumber Anda. Model kemudian memprediksi bagaimana adegan tersebut akan bergerak maju seiring waktu berdasarkan prompt Anda.

Misalnya: Anda menyediakan foto danau gunung saat matahari terbit. Prompt Anda mengatakan "riak lembut menyebar di permukaan air saat kabut pagi melayang." Bingkai pertama video output adalah foto Anda. Bingkai berikutnya menunjukkan air dan kabut yang bergerak sesuai prompt.

Ini berbeda dengan text-to-video, di mana model menghasilkan bingkai pertama itu sendiri. Image-to-video memberi Anda kontrol yang tepat atas adegan awal.

Anda harus memilih image-to-video ketika: - Anda memiliki foto produk, lanskap, atau potret yang ada yang ingin Anda gerakkan. - Aset merek Anda membutuhkan identitas visual yang konsisten di bingkai pertama. - Anda ingin gerakan terasa mendasari adegan nyata atau spesifik.

Anda harus memilih text-to-video ketika: - Anda sedang menjelajahi ide visual tanpa gambar referensi. - Anda ingin model memutuskan komposisi adegan sepenuhnya. - Kecepatan iterasi lebih penting daripada presisi bingkai pertama.

Prasyarat

Sebelum melakukan panggilan pertama Anda, Anda memerlukan:

Akun xAI di console.x.ai.
Kunci API dari konsol xAI. Simpan ini dalam variabel lingkungan, jangan di-hardcode.
Python 3.8+ atau Node.js 18+ (contoh dalam panduan ini menggunakan keduanya).
URL gambar yang dapat diakses publik, atau gambar yang dienkode base64 sebagai URI data.

Tetapkan kunci Anda sebagai variabel lingkungan:

export XAI_API_KEY="your_key_here"

Instal SDK Python xAI jika Anda ingin klien tingkat tinggi:

pip install xai-sdk

Untuk panggilan HTTP mentah, tidak ada paket tambahan yang diperlukan selain requests (Python) atau fetch (Node.js).

Melakukan permintaan image-to-video pertama Anda

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": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Respons langsung kembali dengan request_id:

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

Video belum siap. Generasi terjadi secara asinkron dalam infrastruktur xAI. Anda perlu melakukan polling untuk hasilnya.

Menggunakan Python (permintaan mentah)

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

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

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

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

Menggunakan gambar base64

Jika gambar Anda lokal atau tidak dapat diakses publik, enkode sebagai URI data:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

Melakukan polling untuk hasilnya

Generasi video bersifat asinkron. API mengembalikan request_id saat video Anda dirender di server xAI. Anda harus melakukan polling endpoint status:

GET https://api.x.ai/v1/videos/{request_id}

Bidang status bergerak melalui nilai-nilai ini:

Status	Arti
`"processing"`	Video masih dalam proses rendering
`"done"`	Video siap, URL ada dalam respons
`"failed"`	Terjadi kesalahan

Respons yang selesai terlihat seperti ini:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

Loop polling Python lengkap

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# Usage
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")

Jaga interval polling pada 5 detik atau lebih tinggi. API memiliki batas laju 60 permintaan per menit (1 per detik). Polling ketat pada beberapa pekerjaan secara bersamaan dapat menghabiskan anggaran itu dengan cepat.

Menggunakan SDK Python xAI

Pustaka xai-sdk membungkus pola asinkron untuk Anda. client.video.generate() mengirimkan pekerjaan dan memblokir hingga video siap, menangani semua polling secara internal:

from xai_sdk import Client
import os

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

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

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

SDK menangani loop polling, pemeriksaan status, dan propagasi kesalahan. Gunakan pendekatan ini ketika Anda menginginkan kode aplikasi yang bersih tanpa mengelola polling HTTP sendiri.

Untuk kontrol yang lebih halus atas interval polling, strategi percobaan ulang, atau logging, pendekatan permintaan mentah memberi Anda lebih banyak fleksibilitas.

Mengontrol resolusi, durasi, dan rasio aspek

API video Grok memberi Anda kontrol langsung atas format output.

Durasi

Parameter duration menerima bilangan bulat dari 1 hingga 15 detik. Standarnya adalah 6.

"duration": 10

Video yang lebih panjang membutuhkan biaya lebih. Klip 10 detik membutuhkan biaya sekitar 10 kali klip 1 detik pada resolusi yang sama.

Resolusi

Dua opsi tersedia:

Nilai	Deskripsi
`"480p"`	Standar. Biaya lebih rendah, generasi lebih cepat.
`"720p"`	Kualitas lebih tinggi. Biaya $0.07/dtk dibandingkan $0.05/dtk.

"resolution": "720p"

Rasio aspek

Parameter aspect_ratio mengontrol dimensi bingkai output:

Nilai	Kasus penggunaan
`"16:9"`	Standar. Layar lebar untuk pemandangan lanskap.
`"9:16"`	Vertikal untuk seluler atau cerita sosial.
`"1:1"`	Persegi untuk Instagram atau thumbnail sosial.
`"4:3"`	Format fotografi atau presentasi klasik.
`"3:4"`	Fotografi potret.
`"3:2"`	Potongan fotografi standar.
`"2:3"`	Format potret tinggi.

Ketika Anda menyediakan image, rasio aspek secara default akan sesuai dengan dimensi gambar sumber. Atur secara eksplisit untuk menimpa atau memotong.

Menggunakan gambar referensi untuk panduan gaya

Parameter reference_images berbeda dari parameter image. Memahami perbedaannya penting.

image: Foto sumber yang menjadi bingkai pertama video. Model menganimasikan dari titik awal ini.

reference_images: Array hingga 7 gambar yang memandu gaya, konten, atau konteks visual dari video yang dihasilkan. Ini bukan bingkai dalam output. Ini memengaruhi bagaimana model merender gerakan dan penampilan.

Gunakan reference_images ketika Anda ingin video output mengadopsi karakteristik visual dari aset yang ada, tetapi bukan sebagai bingkai awal:

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

Dalam contoh ini, product-shot.jpg adalah bingkai pertama. Gambar referensi memandu pencahayaan dan perlakuan gaya.

Anda dapat menyediakan gambar referensi tanpa gambar bingkai pertama sama sekali. Dalam kasus tersebut, model menghasilkan output text-to-video sambil menarik panduan gaya dari referensi.

Memperpanjang dan mengedit video

API mendukung dua operasi tambahan di luar generasi awal.

Memperpanjang video

POST /v1/videos/extensions mengambil video yang ada dan menghasilkan detik tambahan dari titik di mana ia berhenti. Ini berguna untuk membuat klip yang lebih panjang dari beberapa proses generasi, tetap dalam batas 15 detik per panggilan.

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

Respons mengikuti pola asinkron yang sama: polling GET /v1/videos/{request_id} untuk klip yang diperpanjang.

Mengedit video

POST /v1/videos/edits menerapkan modifikasi yang dipandu prompt ke video yang ada. Anda dapat mengubah aspek spesifik dari konten atau gerakan tanpa menghasilkan ulang dari awal.

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

Kedua ekstensi dan pengeditan bersifat asinkron dan menggunakan pola polling yang sama.

Rincian harga: biaya video 10 detik

API video xAI mengenakan biaya untuk dua komponen: pemrosesan gambar input dan durasi video output.

Komponen	Biaya
Gambar input	$0.002 per gambar
Output pada 480p	$0.05 per detik
Output pada 720p	$0.07 per detik

Contoh: Video 10 detik pada 720p

Gambar input: $0.002
Output: 10 detik × $0.07 = $0.70
Total: $0.702

Contoh: Video 6 detik pada 480p (pengaturan standar)

Gambar input: $0.002
Output: 6 detik × $0.05 = $0.30
Total: $0.302

Biaya gambar input berlaku setiap kali Anda mengirimkan permintaan generasi, bahkan jika Anda menggunakan URL gambar yang sama. Rencanakan panggilan generasi Anda dengan sesuai jika Anda melakukan iterasi pada gambar dasar yang sama.

Text-to-video (tanpa parameter image) mengabaikan biaya input $0.002 tetapi mengikuti harga per detik yang sama.

Cara menguji integrasi API video Grok Anda dengan Apidog

Pola asinkron menciptakan tantangan pengujian yang tidak dapat dicakup oleh pengujian permintaan satu kali sederhana. Anda perlu memverifikasi bahwa:

Permintaan generasi mengembalikan request_id.
Permintaan polling menangani status "processing" dengan benar saat menunggu.
Respons akhir memiliki status == "done" dan URL video yang tidak kosong.

Skenario Uji Apidog merangkai langkah-langkah ini menjadi satu alur otomatis. Berikut cara membangunnya:

Langkah 1: Buat Skenario Uji baru

Di Apidog, buka modul Tests dan klik tombol + untuk membuat skenario baru. Beri nama "Grok image-to-video async flow."

Langkah 2: Tambahkan permintaan generasi

Tambahkan langkah permintaan POST kustom:

URL: https://api.x.ai/v1/videos/generations
Metode: POST
Header: Authorization: Bearer {{xai_api_key}}
Body (JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

Langkah 3: Ekstrak request_id

Setelah langkah POST, tambahkan pemroses Extract Variable. Konfigurasikan:

Nama variabel: video_request_id
Sumber: Badan respons
Metode ekstraksi: JSONPath
Ekspresi JSONPath: $.request_id

Apidog menyimpan nilai yang diekstrak dalam {{video_request_id}} untuk digunakan pada langkah-langkah selanjutnya.

Langkah 4: Bangun loop polling

Tambahkan pemroses loop For. Di dalam loop, tambahkan permintaan polling:

URL: https://api.x.ai/v1/videos/{{video_request_id}}
Metode: GET
Header: Authorization: Bearer {{xai_api_key}}

Tambahkan pemroses Extract Variable di dalam loop untuk menangkap status saat ini:

Nama variabel: video_status
JSONPath: $.status

Tambahkan pemroses Wait (5000ms) setelah ekstraksi status untuk menghindari mencapai batas laju.

Atur kondisi Break If loop: {{video_status}} == "done".

Langkah 5: Tegaskan URL video

Setelah loop For, tambahkan langkah GET terakhir ke endpoint polling yang sama. Tambahkan pemroses Assertion:

Bidang: $.video.url
Kondisi: Tidak kosong

Penegasan ini mengkonfirmasi bahwa URL video sudah ada sebelum pengujian Anda lulus.

Untuk melihat lebih dalam tentang cara menguji API asinkron dengan Apidog, termasuk pola polling yang lebih kompleks dan integrasi CI/CD, lihat panduan khusus tersebut.

Menjalankan skenario

Klik Run di tampilan skenario uji. Apidog menjalankan POST, mengekstrak request_id, melingkar polling hingga status == "done", dan kemudian mengevaluasi penegasan Anda. Laporan pengujian menunjukkan status dan waktu setiap langkah.

Anda dapat menghubungkan skenario ini ke pipeline CI/CD Anda dengan Apidog CLI:

apidog run --scenario grok-video-async-flow --env production

Kesalahan umum dan perbaikan

401 Unauthorized

Kunci API Anda hilang atau tidak valid. Periksa format header Authorization: Bearer YOUR_XAI_API_KEY. Konfirmasikan kunci aktif di konsol xAI.

422 Unprocessable Entity

Badan permintaan tidak terbentuk dengan baik. Penyebab umum: bidang model hilang, prompt kosong, atau image.url tidak dapat diakses. Uji URL gambar di browser sebelum menggunakannya.

URL gambar tidak dapat diakses

Server xAI harus dapat mengambil URL gambar pada saat generasi. URL pribadi, alamat localhost, atau URL di balik autentikasi akan gagal. Gunakan CDN publik atau URI data base64 sebagai gantinya.

Status tetap "processing" tanpa batas waktu

Generasi dapat memakan waktu antara 30 detik hingga beberapa menit tergantung pada resolusi dan durasi. Jika status tetap "processing" lebih dari 10 menit, pekerjaan mungkin macet. Kirimkan permintaan baru. API xAI saat ini tidak mengekspos sinyal timeout secara terpisah dari "failed".

Kesalahan batas laju (429)

API mengizinkan 60 permintaan per menit dan 1 per detik. Jika Anda melakukan polling beberapa pekerjaan secara bersamaan, atur permintaan Anda secara bertahap. Tambahkan time.sleep(1) antara panggilan polling minimal.

Unggahan Base64 ditolak

Pastikan URI data Anda menyertakan prefiks tipe MIME yang benar. Gunakan data:image/jpeg;base64, untuk file JPEG dan data:image/png;base64, untuk file PNG.

Ketidakcocokan rasio aspek

Ketika Anda mengatur aspect_ratio eksplisit yang sangat berbeda dari proporsi gambar sumber Anda, model dapat memotong (crop) atau memberi bilah hitam (letterbox). Sesuaikan rasio aspek dengan gambar sumber Anda untuk hasil terbaik.

Kesimpulan

API Grok image-to-video memberi Anda jalur langsung dari foto statis ke klip animasi pendek. Anda melakukan POST gambar dan prompt, menerima request_id, polling hingga selesai, dan mengunduh MP4. Model grok-imagine-video menduduki peringkat teratas di papan peringkat Artificial Analysis pada Januari 2026. Lebih dari satu miliar video dihasilkan dalam satu bulan itu. Skala tersebut mencerminkan seberapa mampu model yang mendasarinya.

Pola polling asinkron adalah tempat sebagian besar integrasi salah. Pengujian yang tepat dalam Skenario Uji Apidog mencakup langkah Extract Variable, loop polling dengan kondisi berhenti, dan penegasan URL akhir. Kombinasi itu menangkap masalah sebelum mencapai produksi.

button

Mulai bangun integrasi Anda dengan Apidog secara gratis. Tidak diperlukan kartu kredit.

FAQ

Nama model apa yang saya gunakan untuk API Grok image-to-video?

Nama model adalah grok-imagine-video. Lewatkan sebagai bidang model dalam badan permintaan POST Anda.

Apa perbedaan antara parameter image dan reference_images?

Parameter image mengatur bingkai pertama video output. Model menganimasikan maju dari gambar awal tersebut. Array reference_images menyediakan panduan gaya dan konten tanpa digunakan sebagai bingkai. Anda dapat menggabungkan keduanya dalam permintaan yang sama.

Berapa lama waktu yang dibutuhkan untuk generasi video?

Waktu generasi bervariasi berdasarkan durasi dan resolusi. Video 480p berdurasi 6 detik biasanya memakan waktu 1 hingga 3 menit. Video 720p berdurasi 15 detik mungkin memakan waktu 4 hingga 8 menit. Lakukan polling setiap 5 detik untuk memeriksa status tanpa menghabiskan batas laju Anda.

Dapatkah saya menggunakan file lokal sebagai gambar sumber?

Ya. Enkode file lokal Anda sebagai URI data base64: data:image/jpeg;base64,{encoded_bytes}. Lewatkan string tersebut sebagai nilai url di dalam objek image.

Apa yang terjadi jika saya tidak menentukan aspect_ratio?

Ketika Anda menyediakan parameter image, rasio aspek secara default akan sesuai dengan proporsi asli gambar sumber. Ketika menghasilkan text-to-video tanpa gambar, defaultnya adalah 16:9.

Berapa biaya video 10 detik 720p?

Gambar input berharga $0.002. Output berharga 10 × $0.07 = $0.70. Total: sekitar $0.702 per video.

Apa saja batas lajunya?

API mengizinkan 60 permintaan per menit dan 1 permintaan per detik. Ini mencakup permintaan POST generasi dan permintaan GET polling gabungan.

Bisakah saya memperpanjang video di luar 15 detik?

Ya, menggunakan endpoint POST /v1/videos/extensions. Anda menghasilkan klip awal hingga 15 detik, kemudian memperpanjangnya dengan proses generasi tambahan. Setiap ekstensi juga mengikuti pola polling asinkron.