Grok Resimden Video API Kullanımı (Adım Adım Kılavuz)

Kısaca

Grok resimden videoya API'si, statik bir görüntüyü video klibe dönüştürmek için grok-imagine-video modelini kullanır. Görüntü URL'nizi, bir istemi ve isteğe bağlı ayarları https://api.x.ai/v1/videos/generations adresine POST edersiniz. API hemen bir request_id döndürür. Daha sonra status "done" olana kadar GET /v1/videos/{request_id} adresini yoklarsınız (poll). Süre 1 ila 15 saniye arasında değişir. 480p çıktı için fiyatlandırma saniye başına 0,05 dolardan başlar.

Giriş

28 Ocak 2026'da xAI, genel API erişimi için grok-imagine-video modelini piyasaya sürdü. İlk ay içinde model 1,2 milyar video üretti ve Yapay Analiz metinden videoya liderlik tablosunda bir numaraya yerleşti. Resimden videoya dönüştürme, amiral gemisi yeteneklerinden biridir: API'ye bir fotoğraf ve açıklayıcı bir istem verirsiniz, o da fotoğrafı MP4 olarak indirilebilecek kısa bir video klibe dönüştürür.

Bir görevi gönderdiğiniz ve tamamlanmasını beklediğiniz bu eşzamansız akış, birçok geliştiricinin atladığı bir test zorluğunu beraberinde getirir. İlk POST 200 döndürdüğünde entegrasyonunuz bitmiş sayılmaz. Entegrasyonunuz, yoklama döngüsünün "processing", "done" ve "failed" durumlarını gerçek ağ koşulları altında doğru şekilde ele aldığını onayladığınızda bitmiş demektir.

Apidog'un Test Senaryoları bu sorunu doğrudan çözer. Zincirleme bir dizi oluşturabilirsiniz: /v1/videos/generations adresine POST yapın, request_id'yi çıkarın, status == "done" olana kadar yoklama isteğini döngüye alın, ardından video URL'sinin mevcut olduğunu onaylayın. Bu kılavuzun ilerleyen kısımlarındaki test anlatımını takip etmek için Apidog'u ücretsiz indirin.

Grok Resimden Videoya API'si Nedir?

Grok resimden videoya API'si, xAI'nin video üretim ürününün bir parçasıdır. grok-imagine-video modeli altında çalışır ve çıktı videonun başlangıç karesi olarak bir resim kabul eder. Model, resim içeriğini ve metin istemini inceler, ardından sahneyi canlandırmak için doğal hareketler üretir.

API uç noktası:

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

Kimlik doğrulama standart bir Taşıyıcı (Bearer) token kullanır:

Authorization: Bearer YOUR_XAI_API_KEY

Anahtarınızı xAI konsolundan alabilirsiniz. Aynı API yüzeyi ayrıca metinden videoya dönüştürmeyi (image parametresini atlayın), video uzantılarını ve video düzenlemelerini destekler.

Resimden Videoya İşlemi Nasıl Çalışır?

İstek gövdesindeki image parametresi, çıktı videonun **ilk karesini** belirtir. Model resmi değiştirmez. Ondan başlar. İlk karedeki her piksel, kaynak resminizden gelir. Model daha sonra isteminize göre o sahnenin zaman içinde nasıl ilerleyeceğini tahmin eder.

Örneğin: gün doğumunda bir dağ gölünün fotoğrafını sağlarsınız. İsteminiz "sabah sisi sürüklenirken su yüzeyinde hafif dalgalar yayılıyor" der. Çıktı videonun ilk karesi sizin fotoğrafınızdır. Sonraki kareler, isteme göre canlanan suyu ve sisi gösterir.

Bu, modelin ilk kareyi kendi başına oluşturduğu metinden videoya dönüştürmeden farklıdır. Resimden videoya dönüştürme, başlangıç sahnesi üzerinde tam kontrol sağlar.

Resimden videoya dönüştürmeyi şu durumlarda seçmelisiniz: - Mevcut ürün fotoğraflarınızı, manzaralarınızı veya portrelerinizi hareketlendirmek istiyorsunuz. - Marka varlıklarınızın ilk karede tutarlı bir görsel kimliğe sahip olması gerekiyor. - Hareketin gerçek veya belirli bir sahneye dayandığını hissettirmesini istiyorsunuz.

Metinden videoya dönüştürmeyi şu durumlarda seçmelisiniz: - Referans bir resim olmadan görsel fikirler keşfediyorsunuz. - Modelin sahne kompozisyonuna tamamen karar vermesini istiyorsunuz. - İlk kare hassasiyetinden çok yineleme hızı önemlidir.

Ön Koşullar

İlk çağrınızı yapmadan önce şunlara ihtiyacınız var:

1. console.x.ai adresinden bir **xAI hesabı**.
2. xAI konsolundan bir **API anahtarı**. Bunu sabit kodlamak yerine bir ortam değişkeninde saklayın.
3. **Python 3.8+** veya **Node.js 18+** (bu kılavuzdaki örnekler her ikisini de kullanır).
4. **Herkese açık bir resim URL'si** veya veri URI'si olarak base64 kodlu bir resim.

Anahtarınızı bir ortam değişkeni olarak ayarlayın:

export XAI_API_KEY="your_key_here"

Daha üst düzey istemciyi istiyorsanız xAI Python SDK'sını yükleyin:

pip install xai-sdk

Ham HTTP çağrıları için `requests` (Python) veya `fetch` (Node.js) dışında ek paket gerekmez.

İlk Resimden Videoya İsteğinizi Yapma

Curl Kullanarak

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

Yanıt hemen bir request_id ile gelir:

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

Video henüz hazır değil. Oluşturma xAI'nin altyapısında eşzamansız olarak gerçekleşir. Sonuç için yoklama (poll) yapmanız gerekir.

Python Kullanarak (Ham İstekler)

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

Base64 Resim Kullanarak

Resminiz yerel veya herkese açık değilse, onu bir veri URI'si olarak kodlayın:

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

Sonuç İçin Yoklama

Video oluşturma eşzamansızdır. API, videonuz xAI sunucularında oluşturulurken request_id değerini döndürür. Durum uç noktasını yoklamanız gerekir:

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

Durum alanı şu değerler arasında hareket eder:

Tamamlanmış bir yanıt şöyle görünür:

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

Tam Python Yoklama Döngüsü

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)

# Kullanım
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Süre: {video['duration']}s")

Yoklama aralığını 5 saniye veya daha yüksek tutun. API'nin dakikada 60 istek (saniyede 1) hız limiti vardır. Aynı anda birden fazla işte sıkı yoklama yapmak bu bütçeyi hızla tüketebilir.

xAI Python SDK'sını Kullanma

xai-sdk kütüphanesi eşzamansız deseni sizin için sarmalar. client.video.generate() işi gönderir ve video hazır olana kadar engeller, tüm yoklamayı dahili olarak halleder:

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

SDK, yoklama döngüsünü, durum kontrollerini ve hata yayılımını yönetir. HTTP yoklamasını kendiniz yönetmeden temiz uygulama kodu istediğinizde bu yaklaşımı kullanın.

Yoklama aralıkları, yeniden deneme stratejileri veya loglama üzerinde daha ayrıntılı kontrol için, ham istekler yaklaşımı size daha fazla esneklik sağlar.

Çözünürlük, Süre ve En Boy Oranını Kontrol Etme

Grok video API'si, çıktı formatı üzerinde doğrudan kontrol sağlar.

Süre

duration parametresi 1 ila 15 saniye arasında tamsayıları kabul eder. Varsayılan değer 6'dır.

"duration": 10

Daha uzun videolar daha pahalıya mal olur. Aynı çözünürlükte 10 saniyelik bir klip, 1 saniyelik bir klibin yaklaşık 10 katı maliyetindedir.

Çözünürlük

İki seçenek mevcuttur:

"resolution": "720p"

En Boy Oranı

aspect_ratio parametresi, çıktı kare boyutlarını kontrol eder:

Bir image sağladığınızda, en boy oranı varsayılan olarak kaynak görüntünün boyutlarıyla eşleşir. Geçersiz kılmak veya kırpmak için açıkça ayarlayın.

Stil Rehberliği için Referans Resimler Kullanma

reference_images parametresi, image parametresinden farklıdır. Farkı anlamak önemlidir.

image: Videonun **ilk karesi** haline gelen kaynak fotoğraf. Model bu başlangıç noktasından animasyon oluşturur.

reference_images: Üretilen videonun **stilini, içeriğini veya görsel bağlamını** yönlendiren en fazla 7 resimden oluşan bir dizi. Bunlar çıktıda kareler değildir. Modelin hareket ve görünümü nasıl işlediğini etkilerler.

Çıktı videonun mevcut varlıklardan görsel özellikler almasını istediğinizde, ancak başlangıç karesi olarak değil, reference_images kullanın:

{
  "model": "grok-imagine-video",
  "prompt": "Temiz beyaz bir yüzeyde yavaşça dönen bir ürün",
  "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"
}

Bu örnekte, product-shot.jpg ilk karedir. Referans resimler aydınlatma ve stilistik işlemeyi yönlendirir.

Hiçbir ilk kare resmi olmadan referans resimler sağlayabilirsiniz. Bu durumda, model, referanslardan stil rehberliği alırken metinden videoya bir çıktı üretir.

Videoları Genişletme ve Düzenleme

API, ilk oluşturmanın yanı sıra iki ek işlemi destekler.

Bir Videoyu Genişletme

POST /v1/videos/extensions, mevcut bir videoyu alır ve kaldığı yerden ek saniyeler üretir. Bu, birden çok oluşturma geçişinden daha uzun klipler oluşturmak için kullanışlıdır, çağrı başına 15 saniyelik limit içinde kalarak.

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": "Güneş ışığı içeri girerken sis yükselmeye devam ediyor",
    "duration": 5
  }'

Yanıt aynı eşzamansız deseni izler: genişletilmiş klip için GET /v1/videos/{request_id} adresini yoklayın.

Bir Videoyu Düzenleme

POST /v1/videos/edits, mevcut bir videoya istem rehberliğinde değişiklikler uygular. İçeriğin veya hareketin belirli yönlerini sıfırdan yeniden oluşturmadan değiştirebilirsiniz.

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": "Gökyüzünü derin turuncu tonlarla dramatik bir gün batımına dönüştür"
  }'

Hem uzantılar hem de düzenlemeler eşzamansızdır ve aynı yoklama desenini kullanır.

Fiyatlandırma Detayları: 10 Saniyelik Bir Video Ne Kadar Tutar?

xAI video API'si iki bileşen için ücret alır: giriş görüntüsü işleme ve çıktı video süresi.

Örnek: 720p'de 10 saniyelik video

• Giriş görüntüsü: 0,002 $
• Çıktı: 10 saniye × 0,07 $ = 0,70 $
• Toplam: 0,702 $

Örnek: 480p'de 6 saniyelik video (varsayılan ayarlar)

• Giriş görüntüsü: 0,002 $
• Çıktı: 6 saniye × 0,05 $ = 0,30 $
• Toplam: 0,302 $

Giriş görüntüsü ücreti, aynı görüntü URL'sini yeniden kullansanız bile, her oluşturma isteği gönderdiğinizde uygulanır. Aynı temel görüntü üzerinde yineleme yapıyorsanız, oluşturma çağrılarınızı buna göre planlayın.

Metinden videoya (image parametresi yok) 0,002 $'lık giriş ücretini atlar, ancak aksi takdirde saniye başına aynı fiyatlandırmayı takip eder.

Grok Video API Entegrasyonunuzu Apidog ile Nasıl Test Edersiniz?

Eşzamansız desen, basit tek seferlik istek testlerinin kapsayamayacağı bir test zorluğu yaratır. Şunları doğrulamanız gerekir:

1. Oluşturma isteği bir request_id döndürür.
2. Yoklama isteği beklerken "processing" durumunu doğru şekilde ele alır.
3. Nihai yanıtta status == "done" ve boş olmayan bir video URL'si bulunur.

Apidog'un Test Senaryoları bu adımları tek bir otomatik akışta birleştirir. İşte nasıl oluşturulacağı:

Adım 1: Yeni Bir Test Senaryosu Oluşturun

Apidog'da Testler modülünü açın ve yeni bir senaryo oluşturmak için + düğmesine tıklayın. Adını "Grok resimden videoya eşzamansız akış" olarak belirleyin.

Adım 2: Oluşturma İsteğini Ekleyin

Özel bir POST isteği adımı ekleyin:

• URL: https://api.x.ai/v1/videos/generations
• Yöntem: POST
• Başlık (Header): Authorization: Bearer {{xai_api_key}}
• Gövde (JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Işık ağaçların arasından süzülürken sudan hafif sis yükseliyor",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

Adım 3: request_id'yi Çıkarın

POST adımından sonra bir **Değişken Çıkarıcı (Extract Variable)** işlemcisi ekleyin. Şunu yapılandırın:

• Değişken adı: video_request_id
• Kaynak: Yanıt gövdesi
• Çıkarım yöntemi: JSONPath
• JSONPath ifadesi: $.request_id

Apidog, çıkarılan değeri daha sonraki adımlarda kullanmak üzere {{video_request_id}} içinde saklar.

Adım 4: Yoklama Döngüsünü Oluşturun

Bir **For** döngüsü işlemcisi ekleyin. Döngünün içine yoklama isteğini ekleyin:

• URL: https://api.x.ai/v1/videos/{{video_request_id}}
• Yöntem: GET
• Başlık (Header): Authorization: Bearer {{xai_api_key}}

Mevcut durumu yakalamak için döngünün içine bir **Değişken Çıkarıcı (Extract Variable)** işlemcisi ekleyin:

• Değişken adı: video_status
• JSONPath: $.status

Hız sınırına takılmamak için durum çıkarımından sonra bir **Bekle (Wait)** işlemcisi (5000ms) ekleyin.

Döngünün **Kesme Koşulu (Break If)** değerini {{video_status}} == "done" olarak ayarlayın.

Adım 5: Video URL'sini Doğrulayın

For döngüsünden sonra, aynı yoklama uç noktasına son bir GET adımı ekleyin. Bir **Doğrulama (Assertion)** işlemcisi ekleyin:

• Alan: $.video.url
• Koşul: Boş değil

Bu doğrulama, testiniz geçmeden önce video URL'sinin mevcut olduğunu onaylar.

Daha karmaşık yoklama desenleri ve CI/CD entegrasyonu dahil olmak üzere Apidog ile eşzamansız API'lerin nasıl test edileceğine dair daha derinlemesine bir bakış için, ilgili özel kılavuza bakın.

Senaryoyu Çalıştırma

Test senaryosu görünümünde Çalıştır'a tıklayın. Apidog, POST'u yürütür, request_id'yi çıkarır, status == "done" olana kadar yoklama döngüsünü çalıştırır ve ardından doğrulamalarınızı değerlendirir. Test raporu, her adımın durumunu ve zamanlamasını gösterir.

Bu senaryoyu Apidog CLI ile CI/CD pipeline'ınıza dahil edebilirsiniz:

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

Yaygın Hatalar ve Düzeltmeler

401 Yetkilendirilmemiş (Unauthorized)

API anahtarınız eksik veya geçersiz. Authorization başlık biçimini kontrol edin: Bearer YOUR_XAI_API_KEY. Anahtarın xAI konsolunda etkin olduğunu onaylayın.

422 İşlenemeyen Varlık (Unprocessable Entity)

İstek gövdesi yanlış biçimlendirilmiş. Yaygın nedenler: model alanı eksik, prompt boş veya image.url erişilemiyor. Kullanmadan önce resim URL'sini bir tarayıcıda test edin.

Resim URL'si erişilemiyor

xAI sunucularının oluşturma sırasında resim URL'sini alabilmesi gerekir. Özel URL'ler, localhost adresleri veya kimlik doğrulama arkasındaki URL'ler başarısız olacaktır. Bunun yerine genel bir CDN veya base64 veri URI'si kullanın.

Durum süresiz olarak "processing" kalıyor

Oluşturma, çözünürlüğe ve süreye bağlı olarak 30 saniyeden birkaç dakikaya kadar sürebilir. Durum 10 dakikadan fazla "processing" kalırsa, iş takılmış olabilir. Yeni bir istek gönderin. xAI API'si şu anda "failed" durumundan ayrı bir zaman aşımı sinyali sunmamaktadır.

Hız limiti hataları (429)

API dakikada 60 ve saniyede 1 isteğe izin verir. Birden fazla işi eş zamanlı olarak yokluyorsanız, isteklerinizi kademelendirin. Yoklama çağrıları arasına en az time.sleep(1) ekleyin.

Base64 yüklemesi reddedildi

Veri URI'nizin doğru MIME türü önekini içerdiğinden emin olun. JPEG dosyaları için data:image/jpeg;base64, ve PNG dosyaları için data:image/png;base64, kullanın.

En boy oranı uyumsuzluğu

Kaynak görüntünüzün oranlarından önemli ölçüde farklı bir aspect_ratio açıkça ayarladığınızda, model kırpma veya harf kutusu (letterbox) yapabilir. En iyi sonuçlar için en boy oranını kaynak görüntünüzle eşleştirin.

Sonuç

Grok resimden videoya API'si, statik bir fotoğraftan kısa, animasyonlu bir klibe doğrudan bir yol sunar. Resmi ve istemi POST eder, bir request_id alır, bitene kadar yoklar ve MP4'ü indirirsiniz. grok-imagine-video modeli, Ocak 2026'da Yapay Analiz liderlik tablosunun en üstünde yer aldı. O tek ayda bir milyardan fazla video üretildi. Bu ölçek, temel modelin ne kadar yetenekli olduğunu yansıtmaktadır.

Eşzamansız yoklama modeli, çoğu entegrasyonun yanlış gittiği yerdir. Apidog'un Test Senaryolarındaki doğru bir test, Değişken Çıkarıcı adımını, kesme koşullu yoklama döngüsünü ve son bir URL doğrulamasını kapsar. Bu kombinasyon, sorunları üretime ulaşmadan önce yakalar.

Apidog'u ücretsiz kullanarak entegrasyonunuzu oluşturmaya başlayın. Kredi kartı gerekmez.

Sıkça Sorulan Sorular

Grok resimden videoya API'si için hangi model adını kullanmalıyım?

Model adı grok-imagine-video'dur. POST isteği gövdesindeki model alanına bunu iletin.

image ve reference_images parametreleri arasındaki fark nedir?

image parametresi, çıktı videonun ilk karesini ayarlar. Model, o başlangıç görüntüsünden ileriye doğru animasyon oluşturur. reference_images dizisi, kare olarak kullanılmadan stil ve içerik rehberliği sağlar. Her ikisini de aynı istekte birleştirebilirsiniz.

Video oluşturma ne kadar sürer?

Oluşturma süresi süreye ve çözünürlüğe göre değişir. 6 saniyelik 480p bir video genellikle 1 ila 3 dakika sürer. 15 saniyelik 720p bir video 4 ila 8 dakika sürebilir. Hız limitinizi aşmadan durumu kontrol etmek için her 5 saniyede bir yoklama yapın.

Kaynak resim olarak yerel bir dosya kullanabilir miyim?

Evet. Yerel dosyanızı base64 veri URI'si olarak kodlayın: data:image/jpeg;base64,{encoded_bytes}. Bu dizeyi image nesnesinin içindeki url değeri olarak geçirin.

aspect_ratio belirtmezsem ne olur?

Bir image parametresi sağladığınızda, en boy oranı varsayılan olarak kaynak görüntünün doğal oranlarıyla eşleşir. Görüntüsüz metinden videoya dönüştürme yaparken varsayılan değer 16:9'dur.

10 saniyelik 720p bir video ne kadara mal olur?

Giriş görüntüsü 0,002 $ maliyetindedir. Çıktı 10 × 0,07 $ = 0,70 $ maliyetindedir. Toplam: video başına yaklaşık 0,702 $.

Hız limitleri nelerdir?

API, dakikada 60 ve saniyede 1 isteğe izin verir. Bu, hem oluşturma POST hem de yoklama GET isteklerini birleşik olarak kapsar.

Bir videoyu 15 saniyenin ötesine uzatabilir miyim?

Evet, POST /v1/videos/extensions uç noktasını kullanarak. 15 saniyeye kadar bir başlangıç klip oluşturur, ardından ek oluşturma geçişleriyle genişletirsiniz. Her uzatma ayrıca eşzamansız yoklama desenini izler.