DEV Community

Cover image for Grok Metinden Videoya API Kullanımı (Kapsamlı Rehber)
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Grok Metinden Videoya API Kullanımı (Kapsamlı Rehber)

TL;DR

Grok metinden videoya API'si ile bir metin isteminden video oluşturabilirsiniz. POST /v1/videos/generations çağrısı ile hemen bir request_id alırsınız, ardından durum "done" olana kadar GET /v1/videos/{request_id} ile sorgulama yaparsınız. Model adı grok-imagine-video'dur. Fiyatlandırma, 480p çözünürlükte saniye başına 0,05 dolar olarak başlar. xAI Python SDK'sı bu sorgulamayı otomatik olarak yönetir.

Apidog'u hemen deneyin

Giriş

xAI, Ocak 2026'da yalnızca bir ayda 1,2 milyar video üretti. Bu, Grok metinden videoya API'sinin 28 Ocak 2026'daki lansmanından sonraki ilk aydı. Model, Artificial Analysis metinden videoya liderlik tablosunda da aynı ay birinci oldu. Bu rakamlar, altyapının büyük ölçekte çalıştığını gösteriyor.

Bu rehberde, ilk API isteğinizden başlayarak sorgulama, parametre ayarlama, etkili istemler yazma, referans görseller kullanımı, mevcut videoları uzatma/düzenleme ve hangi kullanımda metinden videoya tercih edilmesi gerektiğine kadar tüm adımları pratik olarak bulacaksınız.

💡 API eş zamansızdır. Yani, video hazır olmadan ön uçta render bekleyemezsiniz. Video oluşturma UI'si geliştiriyorsanız, gerçek kredi harcamadan sorgulama akışınızı test etmeniz gerekir. Apidog'un Akıllı Sahte (Smart Mock) özelliği ile oluşturma ve sorgulama uç noktalarını taklit edebilirsiniz. Böylece arka uç geliştirilirken ön uç ekibiniz video oynatıcı UI'sini rahatça geliştirebilir. Test bölümünde Apidog'un nasıl kullanılacağını bulacaksınız.

Grok Metinden Videoya API'si Nedir?

Grok metinden videoya API'si, xAI'nin https://api.x.ai adresindeki medya oluşturma paketindedir. Bir metin istemi göndererek grok-imagine-video modeliyle sıfırdan kısa video klipler üretebilirsiniz. Kaynak görsel gerekmez.

API, ayrıca görselden görsele (POST /v1/images/generations, model: grok-imagine-image), videoları uzatma ve düzenleme uç noktalarını içerir.

Metinden videoya ile görselden videoya arasındaki ana fark: metinden videoda yalnızca kelimeler verirsiniz, sahne ve görsellik tamamen açıklamanıza göre oluşur. Kaynak görselle başlamak için Grok görselden videoya API rehberine bakın.

Metinden Videoya Oluşturma Nasıl Çalışır? (Eş Zamansız Desen)

Video oluşturma API'sinde eş zamansız bir akış vardır çünkü video üretimi birkaç saniye ila dakika sürebilir. Akış şu şekildedir:

  1. POST ile isteminizi gönderin.
  2. Yanıt olarak anında bir request_id alın.
  3. Video arka planda oluşturulmaya başlar.
  4. GET /v1/videos/{request_id} ile durumu sorgulayın.
  5. Durum "done" olduğunda, yanıt video URL'sini içerir.

Bu desen, API bağlantılarınızı kısa tutar ve ön ucunuzun yükleme durumu yönetmesini gerektirir.

Ön Koşullar

Başlamadan önce:

  • xAI hesabı: console.x.ai adresinden oluşturun. Faturalandırma bilgisi eklenmeli.
  • API Anahtarı: xAI konsolunda API Anahtarları'ndan oluşturup güvenli bir yere kaydedin. Bearer token olarak kullanacaksınız.

API anahtarını ortam değişkenine atayın:

export XAI_API_KEY="your_api_key_here"
Enter fullscreen mode Exit fullscreen mode

İsteğe bağlı: xAI Python SDK'sını kurmak için:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

API Anahtarı Oluşturma Ekran Görüntüsü

İlk Metinden Videoya İsteğiniz

Uç nokta: POST https://api.x.ai/v1/videos/generations

Gerekli alanlar: model, prompt.

Curl ile 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Yanıt:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode

Python requests ile 

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}")
Enter fullscreen mode Exit fullscreen mode

Video Sonucu için Sorgulama

Bir request_id aldıktan sonra, video tamamlanana kadar döngüde sorgulama yapmalısınız.

Durum değerleri:

  • "processing": hala oluşturuluyor
  • "done": tamamlandı, video URL'si mevcut
  • "failed": hata oluştu

Eksiksiz Python sorgulama döngüsü:

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"
)
Enter fullscreen mode Exit fullscreen mode

Örnek tamamlanmış yanıt:

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

xAI Python SDK ile Otomatik Sorgulama

xAI Python SDK ile sorgulama işlemini elle yazmadan çözebilirsiniz:

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"Süre: {result.video.duration}s")
Enter fullscreen mode Exit fullscreen mode

SDK ile hızlıca üretim alabilirsiniz. Daha fazla kontrol için ham isteklerle kendi sorgulama döngünüzü yazın.

Video Üretimi için Etkili İstemler Yazmak

Başarılı video üretimi için isteminizi şu şekilde yapılandırın:

  • Sahne açıklaması: Konu ve ortamı birlikte tanımlayın. Detaylı açıklama gerçekçi sahneler üretir.
  • Hareket: Ne hareket edecek, nasıl ve hangi yönde belirtin. Örn: "Kamera kupanın etrafında döner; buhar yukarı yükselir."
  • Kamera stili: "Yakın çekim", "havadan drone çekimi" gibi terimler kullanın.
  • Aydınlatma ve ruh hali: "Altın saat", "sisli sabah, melankolik atmosfer" gibi ifadeler kullanın.
  • Stil referansları: "Sinematik", "anime", "stop-motion". Birden fazla stili birleştirmek ilginç sonuçlar verebilir.

Örnek istem yapısı:

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.
Enter fullscreen mode Exit fullscreen mode

Çözünürlük, Süre, En Boy Oranı Parametreleri

Süre 

"duration": 10
Enter fullscreen mode Exit fullscreen mode
  • 1-15 saniye arasında, varsayılan 6 saniye.

Çözünürlük 

"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode
  • "480p" (varsayılan), "720p"

En Boy Oranı 

"aspect_ratio": "9:16"
Enter fullscreen mode Exit fullscreen mode

Mevcut oranlar:

Oran En uygun
16:9 Masaüstü, YouTube
9:16 TikTok, Reels, mobil
1:1 Instagram akışı
4:3 Klasik video
3:4 Dikey mobil içerik
3:2 Standart foto oranı
2:3 Dikey fotoğrafçılık

Tüm Parametrelerle Örnek 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Referans Görseller ile Stil Yönlendirme

reference_images parametresi ile en fazla 7 adet görsel URL'si gönderebilirsiniz. Bunlar, videonun görsel stilini yönlendirir:

{
  "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"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Tutarlı stil için benzer estetikte görseller kullanın. Referans görselde sahne isteminiz yönlendirir; görselden videoda ise kaynak görsel ilk kare olur.

Oluşturulan Videoları Uzatma ve Düzenleme

Bir Videoyu Uzatmak

POST /v1/videos/extensions ile mevcut bir videoya yeni çekimler ekleyebilirsiniz. Orijinal request_id ve yeni bir istem ile çağırın. 15 saniye sınırını aşmak için kullanılır.

Bir Videoyu Düzenlemek

POST /v1/videos/edits ile bir videoyu metin talimatına göre düzenleyebilirsiniz. Stil, sahne veya efektleri değiştirmek için kullanılır.

Her iki uç nokta da eş zamansızdır ve sonucu GET /v1/videos/{request_id} ile sorgulayabilirsiniz.

API Yanıtından Maliyeti Okuma

Tamamlanan yanıtın usage nesnesinde tick cinsinden maliyet bulunur:

"usage": {
  "cost_in_usd_ticks": 500000000
}
Enter fullscreen mode Exit fullscreen mode

Dolar karşılığı: cost_in_usd_ticks / 10_000_000

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Cost: ${cost_in_usd:.4f}")
Enter fullscreen mode Exit fullscreen mode

Fiyatlandırma Tablosu

Çözünürlük Saniye başı 10 sn klip
480p $0.05 $0.50
720p $0.07 $0.70

Her yanıttan tick değerini kaydederek kullanım panosu oluşturabilirsiniz.

Grok Video API'nizi Apidog ile Test Etme

Eş zamansız sorgulama deseni nedeniyle, ön uç kodunuzun yükleme, başarı ve hata durumlarını test etmesi gerekir. Gerçek API ile test maliyetli olacağı için Apidog'un Akıllı Sahte (Smart Mock) özelliğini kullanarak uç noktaları taklit edin.

Apidog'da Akıllı Sahte Ayarları Ekran Görüntüsü

Kullanım Durumu 1: Ön Uç Geliştirme için Smart Mock

  • POST /v1/videos/generations uç noktasını oluşturun, yanıt şeması olarak tek bir request_id dize alanı tanımlayın.
  • GET /v1/videos/{request_id} için, status, video.url, progress ve usage.cost_in_usd_ticks alanlarını içeren yanıt şeması tanımlayın. Sahte yanıtla "status": "done" ve örnek bir MP4 URL'si döndürün.

Artık ön uç ekibi, yükleme, başarı ve hata durumlarını gerçek API kredisi harcamadan test edebilir.

Kullanım Durumu 2: Sorgulama Döngüsü için Test Senaryoları

  • Test senaryonuza POST /v1/videos/generations adımını ekleyin. Yanıttan request_id'yi çıkarıp değişkende saklayın.
  • GET /v1/videos/{{videoRequestId}} adımını ekleyin, döngüye alıp status == "done" olana kadar kontrol edin. 5 sn bekleme ekleyin.
  • Döngüden sonra, $.video.url'nin boş olmadığını doğrulayan bir kontrol ekleyin.

Bu şekilde, sorgulama mantığınız CI ortamında otomatik olarak test edilebilir.

Metinden Videoya mı, Görselden Videoya mı?

Aynı model kullanılsa da farklı kullanımlar için uygundur:

Metinden videoya tercih edin:

  • Sıfırdan içerik üretecekseniz
  • Modelin kompozisyonu özgürce oluşturmasını istiyorsanız
  • Kullanıcıların istem yazdığı bir uygulama geliştiriyorsanız
  • Kaynak görseliniz yoksa

Görselden videoya tercih edin:

  • Belirli bir görseli canlandırmak istiyorsanız
  • Mevcut görseldeki detayları korumak istiyorsanız
  • Tutarlı animasyonlar üretmek için

Daha fazla detay için Grok görselden videoya API rehberine bakabilirsiniz.

Sık Karşılaşılan Hatalar ve Çözümleri

  • 401 Yetkisiz: API anahtarı eksik/hatalı. Bearer token'ı doğru biçimde gönderin, anahtar aktif mi kontrol edin.
  • 429 Çok Fazla İstek: Hız sınırı. Dakikada 60, saniyede 1 istek hakkınız var. Sorgulamalar arası gecikme ekleyin.
  • Durum "failed": İçerik denetiminden geçmedi. İstemi revize edin, hassas ifadeleri çıkarın.
  • Video URL'si 404: Video URL'si geçicidir. Hemen indirin, uzun süre saklamayın.
  • Boş veya donmuş video: Belirsiz veya hareketsiz istemlerde olabilir. Açık hareket talimatları ekleyin.
  • Yavaş sorgulama süreleri: 720p ve uzun klipler daha uzun sürer. Geliştirme için kısa ve düşük çözünürlük kullanın.

Sonuç

Grok metinden videoya API'si ile metin isteminden hızlıca video üretebilir, sorgulama döngüsü ile sonucu çekebilir ve çıktınızın parametrelerini (süre, çözünürlük, oran, stil) kolayca yönetebilirsiniz. Maliyet takibi için cost_in_usd_ticks değerini kullanın. Geliştirme ve test süreçlerinde Apidog ile uç noktaları taklit edin, Test Senaryoları ile entegrasyonunuzu sürekli doğrulayın.

Grok video API'si için sahte sunucunuzu ve test senaryolarınızı Apidog ile hızlıca kurabilirsiniz.

Sıkça Sorulan Sorular (SSS)

Metinden videoya oluşturma için hangi model adını kullanmalıyım?

grok-imagine-video kullanın. Bu, /v1/videos/generations POST isteğinde model alanıdır.

Video oluşturma ne kadar sürer?

Çözünürlük ve süreye göre değişir. 480p kısa klipler 30 saniyeden kısa sürebilir, 720p ve uzun klipler birkaç dakika alabilir. Her 5-10 saniyede bir sorgulama yapın.

15 saniyeden uzun video üretebilir miyim?

Tek seferde mümkün değil, maksimum duration 15 saniye. Daha uzun klipler için POST /v1/videos/extensions ile uzatma yapın.

Oluşturulan videoyu nasıl indiririm?

Sorgulama yanıtındaki result.video.url ile MP4 dosyasını hemen indirin. URL geçicidir.

İstemim içerik denetimini ihlal ederse ne olur?

status "failed" olur. Yanıtta respect_moderation alanı denetimin uygulandığını gösterir. İstemi değiştirip tekrar deneyin.

Video API'si için ücretsiz katman var mı?

xAI, çıktı saniyesi başına ücret alır. Ücretsiz katman yoktur. Kredi kampanyalarını console.x.ai üzerinden kontrol edin.

reference_images ile kaynak görsel arasında fark nedir?

Referans görseller, metinden videoya çalışmasında stil rehberliği sunar. Görselden videoda ise kaynak görsel ilk kare olur.

Kredi harcamadan sorgulama döngüsü nasıl test edilir?

Apidog'un Smart Mock özelliği ile her iki uç noktayı taklit edin. "processing" ve "done" durumları için sahte yanıtlar ayarlayın, kodunuz gerçek API'ye dokunmadan çalışır.

Top comments (0)