Gemini Omni API: Google Interactions ile video üretimi ve düzenleme

Gemini Omni API doğrudan ne yapar?

Gemini Omni API, Google’ın Interactions API’si üzerinden metinden veya görselden video üretir ve üretilen videoyu sonraki bir doğal dil isteğiyle düzenler. Bu rehber doğrudan Google Gemini API entegrasyonunu anlatır; LLMTR modeli, LLMTR anahtarı veya LLMTR uç noktası kullanmaz. Sağlayıcı adresi https://generativelanguage.googleapis.com/v1beta/interactions, kimlik bilgisi ise GEMINI_API_KEY ortam değişkenidir.

Google 27 Ağustos 2026’da gemini-omni-1.1-flash kimliğini genel kullanıma açtı. Eski gemini-omni-flash-preview uç noktası için 30 Eylül 2026’da kullanımdan kaldırma duyuruldu. Yeni bir entegrasyonu kararlı kimlikle kurun; sağlayıcı öneki ekleyerek google/gemini-omni gibi bir kimlik üretmeyin.

Modeli, uç noktayı ve çıktı yolunu eşleştirin

Interactions kaynağı bir işin kimliğini, durumunu ve adımlarını taşır. Arka plan isteğinde POST çağrısı hızlıca bir interaction id döndürür; istemci aynı kimliği GET /v1beta/interactions/{id} ile sorgular. Durum completed olmadan ikinci düzenleme turunu başlatmayın.

Aşağıdaki ayrım, sohbet yanıtı veya uzun süreli işlem nesnesi varsayarak yanlış alan okumanızı önler. URI teslimi seçerseniz Files API’de ACTIVE durumunu izlemek ayrı bir akıştır; bu örnek inline video verisi için Interaction durumunu izler.

Arka planda üretin, tamamlanınca düzenleyin

Örnek, resmi Python SDK’sını doğrudan Google hesabına bağlar. İlk çağrı background=True ile videoyu başlatır. wait_until_done yalnızca status değeri in_progress iken beş saniye arayla client.interactions.get çağırır; completed dışındaki son durumları başarı saymaz. Bu, uydurma bir operation.name veya done alanına bağlı değildir.

İlk Interaction tamamlandıktan sonra ikinci çağrı aynı modeli ve first.id değerini previous_interaction_id olarak gönderir. Bu kimlik Google’ın sakladığı video bağlamını devam ettirir; önceki MP4 dosyasını yeniden yüklemek gerekmez. store=False kullanmayın, çünkü Google bu ayarda sonraki turlarda previous_interaction_id ile düzenlemenin çalışmayacağını belirtiyor.

Doğrudan Google SDK ile üretim, durum sorgusu ve düzenleme

import base64
import os
import time
from pathlib import Path

from google import genai

MODEL = "gemini-omni-1.1-flash"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

def wait_until_done(interaction):
    while interaction.status == "in_progress":
        time.sleep(5)
        interaction = client.interactions.get(id=interaction.id)
    if interaction.status != "completed":
        raise RuntimeError(
            f"Interaction ended with status: {interaction.status}"
        )
    return interaction

first = wait_until_done(
    client.interactions.create(
        model=MODEL,
        input=(
            "A matte white ceramic cup on a wooden table, soft morning light, "
            "slow camera push-in, quiet ambient room sound."
        ),
        response_format={"type": "video"},
        background=True,
    )
)

edited = wait_until_done(
    client.interactions.create(
        model=MODEL,
        previous_interaction_id=first.id,
        input=(
            "Change only the cup to matte blue. Keep the framing, lighting, "
            "camera movement, table, and sound unchanged."
        ),
        response_format={"type": "video"},
        background=True,
    )
)

if edited.output_video is None or not edited.output_video.data:
    raise RuntimeError("Completed interaction has no inline video data")

video_bytes = base64.b64decode(edited.output_video.data)
Path("edited-cup.mp4").write_bytes(video_bytes)

SDK kolaylık alanını REST adımlarıyla karıştırmayın

Python SDK, son video içeriğini interaction.output_video alanında birleştirir. Ham REST yanıtı aynı kolaylık alanını garanti etmez. REST kullanıyorsanız steps dizisinde type değeri model_output olan adımı, ardından content içinde type değeri video olan öğeyi bulun; inline teslimde base64 veri data alanındadır.

Google’ın güncel notuna göre GET /v1beta/interactions/{id}, ilk istek delivery uri ile oluşturulsa bile videoyu şu anda data alanında inline base64 olarak döndürüyor. URI yalnızca ilk oluşturma yanıtında veya SSE akışında garanti ediliyor. Bu yüzden REST kodu hem teslim biçimini hem içerik türünü doğrulamalı; output_text içinde video aramamalıdır.

Düzenleme isteğini dar ve test edilebilir yazın

İlk istemde sahne, kamera hareketi, ışık ve ses beklentisini açıkça tanımlayın. Düzenleme turunda yalnızca değişecek öğeyi söyleyin ve korunacak öğeleri kısa biçimde sabitleyin. Böylece ilk video ile düzenlenmiş video arasındaki farkı insan incelemesinde açıklayabilirsiniz; örnekte yalnızca kupanın rengi değişmelidir.

Bir düzenleme başarısız olduğunda aynı interaction id üzerinde belirsiz istekleri art arda yığmayın. Son tamamlanan iyi sürümün kimliğini saklayın, tek değişkenli yeni bir istem gönderin ve elde edilen dosyayı yayımlamadan önce görsel, ses ve süre açısından inceleyin.

Üretim akışında kimlikleri ve hataları koruyun

Interaction kimliğini iş kaydınızla ilişkilendirin, fakat API anahtarını, müşteri istemini veya üretilen base64 videoyu uygulama loglarına yazmayın. Ağ hatalarında aynı üretim isteğini körlemesine yeniden göndermek iki ayrı video işi başlatabilir; önce elinizdeki etkileşim kimliğini sorgulayın. completed dışındaki bir durumu başarılı dosya gibi sunmayın.

Bu örnek canlı çağrıyla çalıştırılmadı ve video sonucu üretilmedi. Hesap erişimi, bölgesel uygunluk, güvenlik filtreleri ve gerçek tamamlanma süresi kendi Google projenizde doğrulanmalıdır. Yüklenmiş videoları düzenleme için ayrıca bölge ve girdi süresi sınırlamaları vardır; bu örnek modelin kendi ürettiği videoyu durumlu turla düzenler.

• İlk tur completed olmadan previous_interaction_id ile ikinci turu başlatmayın.
• failed, cancelled, incomplete veya requires_action durumlarını başarılı çıktı olarak kaydetmeyin.
• Önizleme kimliğini yeni kodda kullanmayın; geçişi 30 Eylül 2026’dan önce bitirin.
• İndirilen MP4’ü açarak görsel değişikliği ve korunması istenen ses ile hareketi inceleyin.

Sık sorulan sorular

Bu örnek LLMTR üzerinden mi çalışır?

Hayır. Doğrudan Google Gemini API kullanır. GEMINI_API_KEY ve generativelanguage.googleapis.com adresi Google’a aittir; LLMTR anahtarı, LLMTR taban adresi veya sağlayıcı önekli bir LLMTR model kimliği kullanılmaz.

Düzenleme için videoyu tekrar yüklemeli miyim?

Modelin ilk turda ürettiği video için gerekmez. İlk Interaction completed olduktan sonra onun id değerini previous_interaction_id olarak gönderin. Yüklenmiş harici bir videoyu düzenleme akışı ise Files API ve ayrı sınırlamalar içerir.

REST yanıtında output_video neden yok?

output_video Python ve JavaScript SDK’larının kolaylık alanıdır. Ham REST yanıtında steps içindeki model_output adımının video content öğesini okuyun; inline sonuçta base64 veri data alanında bulunur.

gemini-omni-flash-preview kullanmaya devam edebilir miyim?

Yeni entegrasyon için gemini-omni-1.1-flash kullanın. Google, preview uç noktası için 30 Eylül 2026’da kullanımdan kaldırma duyurdu; mevcut çağrıları bu tarihten önce kararlı kimliğe taşıyın.

İlgili yazılar

• Gemini Omni nedir? Video üretimi ve multimodal API rehberi
• Gemini Interactions API nedir? generateContent'ten agent state'e geçiş

• Model kataloğu
• Güvenlik dokümantasyonu
• OpenAI / OpenRouter