DEV Community

Cover image for Grok Resimden Video API Kullanımı (Adım Adım Kılavuz)
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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.

Apidog'u bugün deneyin

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 numara oldu. Resimden videoya dönüştürme, amiral gemisi özelliklerden biri: 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ğu getirir. İlk POST 200 döndürdüğünde entegrasyonunuz bitmiş olmaz. 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 tamamlanır.

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

Kimlik doğrulama için standart Bearer token kullanılır:

Authorization: Bearer YOUR_XAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

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

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

İstek gövdesindeki image parametresi, çıktı videonun ilk karesini belirtir. Model resmi değiştirmez, doğrudan o kareden 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.

Örnek: Bir göl fotoğrafı verin, isteminiz "sabah sisi sürüklenirken su yüzeyinde hafif dalgalar yayılıyor" olsun. Çıktının ilk karesi sizin fotoğrafınızdır; sonraki kareler, su ve sisin canlanmış halini gösterir.

Metinden videoya dönüştürmeden farkı: Model, ilk kareyi kendi başına oluşturmaz, gönderdiğiniz resimden başlar. Böylece başlangıç sahnesi üzerinde tam kontrol sağlanır.

Resimden videoya tercih edin:

  • Ürün fotoğraflarınızı veya marka görsellerinizi hareketlendirmek istiyorsanız.
  • İlk karede tutarlı bir görsel kimlik gereksiniminiz varsa.
  • Hareketin belirli bir sahneye dayalı olmasını istiyorsanız.

Metinden videoya tercih edin:

  • Referans bir görüntünüz yoksa.
  • Modelin sahne kompozisyonunu kendi başına oluşturmasını istiyorsanız.
  • İlk kare hassasiyeti önemli değilse.

Ön Koşullar

Başlamadan önce:

  1. console.x.ai adresinden xAI hesabı alın.
  2. xAI konsolundan API anahtarınızı alın ve bir ortam değişkeninde saklayın.
  3. Python 3.8+ veya Node.js 18+ kurulu olmalı.
  4. Herkese açık bir resim URL'si veya base64 kodlu bir resim dosyanız olmalı.

Örnek Görsel

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

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

Daha üst düzey istemci için xAI Python SDK'sı:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Ham HTTP çağrıları için ek paket gerekmez (requests/fetch yeterli).

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

Yanıt:

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

Video hazır değil; yoklama gereklidir.

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

Base64 Resim Kullanarak

Yerel/özel bir dosya için:

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

Sonuç İçin Yoklama

Video oluşturma eşzamansızdır. request_id ile durum uç noktasını yoklayın:

GET https://api.x.ai/v1/videos/{request_id}
Enter fullscreen mode Exit fullscreen mode

Durumlar:

Durum Anlamı
"processing" Video işleniyor
"done" Video hazır, URL yanıtta
"failed" Bir hata oluştu

Tamamlanmış örnek yanıt:

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

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

Yoklama aralığını 5 saniye ve üzeri tutun. API'nin dakikada 60 istek limiti vardır.

xAI Python SDK'sını Kullanma

xai-sdk ile eşzamansız desen otomatik olarak yönetilir:

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

SDK, yoklama, hata yönetimi ve durum kontrollerini sizin için yapar.

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

Grok video API'si çıktı üzerinde tam kontrol sunar.

Süre

duration parametresi 1–15 saniye arası değer alır (varsayılan: 6).

"duration": 10
Enter fullscreen mode Exit fullscreen mode

Daha uzun videolar daha pahalıdır.

Çözünürlük

Değer Açıklama
"480p" Varsayılan. Daha ucuz, hızlı üretim.
"720p" Yüksek kalite, daha pahalı. 
"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

En Boy Oranı

Değer Kullanım Durumu
"16:9" Geniş ekran, manzara
"9:16" Dikey, mobil/sosyal medya
"1:1" Kare, küçük resimler
"4:3" Klasik fotoğraf/sunum
"3:4" Portre
"3:2" Standart fotoğraf
"2:3" Uzun portre

Bir image verdiğinizde, varsayılan olarak kaynak boyutunu kullanır. Farklı bir oran için açıkça belirtin.

Stil Rehberliği için Referans Resimler Kullanma

  • image: Videonun ilk karesi olan kaynak fotoğraf.
  • reference_images: Videonun stilini, içeriğini veya görsel bağlamını yönlendiren maksimum 7 resim. Bunlar kare olarak kullanılmaz.

Örnek:

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

İlk kare product-shot.jpg olur, referans resimler ise stil ve aydınlatmayı yönlendirir.

İlk kare olmadan sadece referanslarla da metinden videoya çıkışı alabilirsiniz.

Videoları Genişletme ve Düzenleme

Bir Videoyu Genişletme

Mevcut bir videoyu uzatmak için:

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

Yine eşzamansız — yoklama ile ilerleyin.

Bir Videoyu Düzenleme

Mevcut bir videoda düzenleme yapmak için:

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

Genişletme ve düzenleme işlemleri de yoklama gerektirir.

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

Bileşen Maliyet
Giriş görüntüsü Resim başına 0,002 $
480p çıktı Saniye başına 0,05 $
720p çıktı Saniye başına 0,07 $

Örnek: 720p'de 10 saniyelik video

  • Giriş: 0,002 $
  • Çıktı: 10 × 0,07 $ = 0,70 $
  • Toplam: 0,702 $

Örnek: 480p'de 6 saniyelik video

  • Giriş: 0,002 $
  • Çıktı: 6 × 0,05 $ = 0,30 $
  • Toplam: 0,302 $

Aynı görüntü URL'sini tekrar kullansanız bile, her istek için giriş ücreti alınır.

Metinden videoya (image yok) 0,002 $ giriş ücreti alınmaz.

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

Eşzamansız desen, klasik tek seferlik istek testlerinin ötesinde bir otomasyon gerektirir. Doğrulanması gerekenler:

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

Apidog'un Test Senaryoları ile bu akışı otomatikleştirin:

Adım 1: Yeni Test Senaryosu Oluşturun

  • Apidog Testler modülünden yeni bir senaryo oluşturun. Örn: "Grok resimden videoya eşzamansız akış".

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

  • POST isteği ekleyin:

    • URL: https://api.x.ai/v1/videos/generations
    • Header: Authorization: Bearer {{xai_api_key}}
    • Body: 
    {
  "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

  • Değişken Çıkarıcı ekleyin:
    • Ad: video_request_id
    • JSONPath: $.request_id

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

  • For döngüsü oluşturun, içinde:
    • GET isteği: https://api.x.ai/v1/videos/{{video_request_id}}
    • Authorization Header: Bearer {{xai_api_key}}
    • Değişken Çıkarıcı: video_status ($.status)
    • Wait: 5000ms
    • Break If: {{video_status}} == "done"

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

  • Son bir GET adımı ekleyin.
  • Assertion: $.video.url boş değil.

Senaryoyu çalıştırın; Apidog tüm akışı otomatikleştirir. CLI ile CI/CD entegrasyonuna da uygundur:

apidog run --scenario grok-video-async-flow --env production
Enter fullscreen mode Exit fullscreen mode

Yaygın Hatalar ve Düzeltmeler

401 Yetkilendirilmemiş

  • API anahtarınızı ve Authorization başlığını kontrol edin.

422 İşlenemeyen Varlık

  • Gövdeyi ve zorunlu alanları doğrulayın. Görüntü URL'sinin erişilebilir olduğundan emin olun.

Resim URL'si erişilemiyor

  • Genel bir CDN veya base64 veri URI'si kullanın.

Durum hep "processing"

  • Uzun sürede de tamamlanabilir; 10 dakikadan uzun sürerse yeni istek gönderin.

429 Hız limiti hatası

  • Dakikada 60, saniyede 1 istek limitine uyun. Yoklama aralığını artırın.

Base64 yüklemesi reddedildi

  • Doğru MIME önekini (data:image/jpeg;base64,) ekleyin.

En boy oranı uyumsuzluğu

  • Kaynak görsel oranını ve aspect_ratio'yu uyumlu seçin.

Sonuç

Grok resimden videoya API'si, statik bir fotoğraftan kısa, animasyonlu bir klibe doğrudan yol sunar. Fotoğraf ve istemi POST edersiniz, bir request_id alırsınız, bitene kadar yoklarsınız, ardından MP4'ü indirirsiniz. grok-imagine-video modeli Ocak 2026'da liderliğe ulaştı ve ilk ayında 1 milyardan fazla video üretildi.

Eşzamansız yoklama modeli, entegrasyonlarda en çok hata yapılan noktadır. Apidog'un Test Senaryoları ile Değişken Çıkarıcı, kesme koşullu yoklama döngüsü ve son doğrulama adımlarını otomatikleştirerek entegrasyon hatalarını erkenden yakalayabilirsiniz.

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. Gövdede model alanı olarak iletin.

image ve reference_images parametreleri arasındaki fark nedir?

  • image: Videonun ilk karesini belirler. reference_images: Stil ve içerik rehberliği sağlar, kare olarak kullanılmaz.

Video oluşturma ne kadar sürer?

  • 6 saniyelik 480p video genellikle 1–3 dakika, 15 saniyelik 720p video 4–8 dakika sürebilir. Her 5 saniyede bir yoklama önerilir.

Kaynak resim olarak yerel dosya kullanabilir miyim?

  • Evet, base64 veri URI'si olarak gönderin: data:image/jpeg;base64,{encoded_bytes}.

aspect_ratio belirtmezsem ne olur?

  • image varsa, oran otomatik olarak görselin doğal oranı olur. Görüntüsüz metinden videoda varsayılan 16:9'dur.

10 saniyelik 720p bir video ne kadar?

  • Giriş: 0,002 $, çıktı: 10 × 0,07 $ = 0,70 $, toplam: 0,702 $.

Hız limitleri nelerdir?

  • Dakikada 60 ve saniyede 1 istek limiti vardır; POST ve GET toplamı için geçerli.

Bir videoyu 15 saniyenin ötesine uzatabilir miyim?

  • Evet, POST /v1/videos/extensions ile ek oluşturma geçişleriyle uzatabilirsiniz. Her uzatma ayrı yoklama gerektirir.

Top comments (0)