İyi bir Rivya API entegrasyonu, tek modele yapılan tek istekten ibaret değildir.

Gerçek ürün iş akışlarının çoğunda küçük bir zincir vardır: doğru modeli seçmek, girdiyi hazırlamak, gerektiğinde referans dosyalarını yüklemek, bir iş göndermek, durumu izlemek, kredileri ele almak ve sonuç hazır olduğunda ürünü bilgilendirmek.

Bu makale planlama şeklini gösterir. En kısa çalıştırılabilir yol için Rivya API Hızlı Başlangıç sayfasını, kesin istek alanları için API dokümanlarını kullanın.

Ürün Anıyla Başlayın

Endpoint seçmeden önce ürün anını tek cümlede tarif edin.

Örnekler:

Satıcı listing brief'i gönderdiğinde ürün görseli taslağı oluştur.
Kampanya yöneticisi bir still yönünü onayladıktan sonra kısa video konsepti üret.
Dahili araştırma aracında bir chat turn gönder ve yanıtı kullanıcıya stream et.
Bir referans görseli yükle, desteklenen model isteğini gönder ve sonuç hazır olduğunda kullanıcıyı bilgilendir.

Bu cümle entegrasyonun gevşek API çağrıları koleksiyonuna dönüşmesini önler.

Kod Yazmadan Önce İş Akışını Haritalayın

Request schema'yı açmadan önce bu tabloyu kullanın.

İş akışı adımı	Ürün sorusu	API alanı
Hesap erişimi	Kullanım hangi Rivya hesabına ait?	API Kimlik Doğrulaması
Model seçimi	Bu işe hangi public model ID uyar?	API Modelleri
Referans girdisi	Modelin yüklenmiş medyaya ihtiyacı var mı?	Files API
Generation	Bu async image, video veya audio işi mi?	Oluşturma İşi Başlatma
Chat	Bu generation işi yerine chat model turn'ü mü?	Chat API
Status	Ürün sonucun hazır olduğunu nasıl bilecek?	Oluşturma Durumu
Completion event	Başka bir sistem imzalı callback almalı mı?	API Webhooks
Credits	Ekip maliyeti nasıl anlayacak?	API Kredileri

İş akışı, her API alanının var olma nedeni anlaşılacak kadar net olmalıdır.

1. Adım: Entegrasyon İçin Key Oluşturun

Onu kullanacak belirli uygulama, ortam veya iş akışı için bir API key oluşturun.

Tek key'i her şey için kullanmaktan kaçının. Key'leri amaca göre adlandırmak sonraki incelemeyi kolaylaştırır:

production-image-workflow
staging-video-tests
internal-chat-assistant
webhook-smoke-test

Key'i saklamadan önce API Kimlik Doğrulaması sayfasını okuyun. Tam secret yalnızca bir kez gösterilir, bu yüzden ekibiniz onu hemen doğru server-side secret store'a kaydetmelidir.

2. Adım: Public API Listesinden Model Seçin

Bir model manuel testte çalıştı diye onu doğrudan hard-code etmeyin.

Şunları doğrulamak için API Modelleri ve Model API Referansı kullanın:

public model ID
API üzerinden kullanılabilir olup olmadığı
desteklenen input mode
prompt ve parameter beklentileri
Files API gerekip gerekmediği
credit davranışı ve readiness notları

Birçok entegrasyon burada daha temiz hale gelir. Manuel Studio testi için mükemmel olan bir model, otomatik ürün akışı için doğru ilk model olmayabilir.

3. Adım: Files API İlk Sürümün Parçası mı Karar Verin

Model text input ile çalışabiliyorsa ilk sürümü text-only tutun.

Files API yalnızca iş akışı gerçekten referans medyaya ihtiyaç duyduğunda eklenmelidir.

Eklendiğinde şunları tanımlayın:

ürünün hangi dosya türlerini kabul ettiği
dosya cleanup adımından kimin sorumlu olduğu
yükleme başarısız olduğunda ne olacağı
dönen file data'nın model parametrelerine nasıl geçirileceği
aynı dosyanın yeniden mi kullanılacağı yoksa tekrar mı yükleneceği

Bu, kırılgan bir dosya deneyiminin temiz görünen generate butonunun arkasına saklanmasını önler.

4. Adım: Tek Generation İşi Gönderin

Görsel, video ve ses generation için normal desen şudur:

model ID'yi, promptu ve desteklenen params alanlarını hazırlayın
güvenli retry için idempotency key ekleyin
generation endpoint üzerinden gönderin
public task ID'yi kaydedin
task terminal state'e ulaşana kadar status poll edin

Request şekli için Oluşturma İşi Başlatma, sonuç işleme için Oluşturma Durumu kullanın.

Ürün, queued, processing, succeeded ve failed durumlarını kullanıcıya gösterilebilir state'ler olarak ele almalıdır. Kullanıcıların sistem ayrıntılarını okumasını veya işin neden yavaş olduğunu tahmin etmesini beklemeyin.

5. Adım: Chat Modelleri İçin Chat API Kullanın

Chat modelleri generation endpoint'i değil, Chat API kullanmalıdır.

Bu önemlidir, çünkü chat işi farklı davranır:

chat turn'leri API-created session'lara ait olabilir
non-streaming ve SSE streaming farklı kullanıcı deneyimleri yaratır
image attachments Files API'den gelen file ID'leri kullanır
credit settlement normal async media task yerine chat turn'ü izler

Ürününüz kendi arayüzünde assistant yanıtına ihtiyaç duyuyorsa Chat API doğru yol olabilir. Kullanıcı hâlâ fikir keşfediyorsa Rivya Chat veya Studio daha iyi olabilir.

6. Adım: Polling ile Başlayın, Sonra Webhooks Ekleyin

İlk sürüm için polling'i anlamak daha kolaydır.

Şu durumlarda API Webhooks ekleyin:

üründe çok sayıda async iş vardır
bekleyen client'lar doğrudan poll etmemelidir
downstream sistemler imzalı completion event'leri gerektirir
retry ve duplicate handling zaten tasarlanmıştır

Webhook receiver'ları sıkıcı ve katı olmalıdır: signature doğrulayın, duplicate-safe event'leri kabul edin, tek ürün kaydını güncelleyin ve yalnızca loglanması güvenli olanı loglayın.

7. Adım: Kredileri Üründe Görünür Kılın

Rivya API, Studio ile aynı hesap kredilerini kullanır.

Entegrasyonunuz bunun ne kadarını göstereceğine karar vermelidir. En azından ekip şunları bilmelidir:

API key'in hangi hesaba ait olduğu
hangi iş akışının kredi tüketebileceği
krediler çok düşük olduğunda ne olacağı
failed generation state'lerinin nasıl açıklanacağı
kredi ve faturalama soruları için nereye yönlendirme yapılacağı

Kullanıcıya dönük wallet modeli için API Kredileri, Rivya'da Krediler ve Faturalama ve Rivya Credits, Packs ve Plans Nasıl Düşünülmeli sayfalarını kullanın.

Küçük Bir İlk Sürüm

İyi bir ilk sürüm bilinçli olarak sınırlıdır.

Örneğin:

tek API key
seçilmiş tek görsel modeli
henüz file upload yok
tek generation request
tek status polling yolu
ürününüzde basit bir sonuç preview'u
net bir credit error message

Bu sürüm, daha fazla hareketli parça eklemeden önce bağlantıyı kanıtlar.

Daha Tam Bir Sürüm

İlk sürüm çalıştıktan sonra daha dolu bir iş akışı şunları ekleyebilir:

referans görseller veya videolar için Files API
modele özel parameter kontrolleri
ürün kaydınıza bağlı idempotency
completion için signed webhooks
assistant turn'leri için Chat API
chat canlı çıktı istediğinde server-side event stream
failed jobs için admin veya support görünümleri

Her ekleme gerçek bir ürün ihtiyacına yanıt vermelidir. Yalnızca demo'yu daha büyük gösteriyorsa dışarıda bırakın.

Yaygın Entegrasyon Hataları

Şu desenlerden kaçının:

tüm API özellikleriyle aynı anda başlamak
kredi kullanımını hesap sahibinden gizlemek
API akışında Studio-only varsayımlar kullanmak
file uploads'ı sonradan düşünülen ayrıntı gibi ele almak
idempotency olmadan generation request retry etmek
async generation olması gereken işler için Chat API kullanmak
chat turn'leri için generation endpoint kullanmak
full API key, webhook secret veya temporary file details loglamak

En güvenli API iş akışı sahipliği, state'i ve failure handling'i açıkça belirtir.

Sonra Nereye Gidilmeli

Public API hub için Developers sayfasından başlayın.
İlk isteği çalıştırmak için Rivya API Hızlı Başlangıç kullanın.
Model ID seçmeden önce API Modelleri kullanın.
Files API yalnızca model gerçekten referans medyaya ihtiyaç duyduğunda kullanılmalıdır.
Chat turn'leri ve streaming chat responses için Chat API kullanın.
Polling artık yeterli olmadığında API Webhooks kullanın.
İş akışı hâlâ insan keşfine ihtiyaç duyuyorsa otomatikleştirmeden önce Studio Yerine Rivya API Ne Zaman Kullanılır yazısını okuyun.

Rivya API ile Multimodal İş Akışı Kurun