Rivya API ile Çok Modlu İş Akışı Kurun

İ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 belgelerini kullanın.

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

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

Örnekler:

• Satıcı listeleme özetini gönderdiğinde ürün görseli taslağı oluştur.
• Kampanya yöneticisi bir statik görsel yönünü onayladıktan sonra kısa video konsepti üret.
• Dahili araştırma aracında bir sohbet turu gönder ve yanıtı kullanıcıya akışla ilet.
• 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

İstek şemasını açmadan önce bu tabloyu kullanın.

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

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

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

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

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

Anahtarı saklamadan önce API Kimlik Doğrulaması sayfasını okuyun. Tam gizli değer yalnızca bir kez gösterilir, bu yüzden ekibiniz onu hemen doğru sunucu tarafı gizli değer deposuna kaydetmelidir.

2. Adım: Herkese Açık API Listesinden Model Seçin

Bir model manuel testte çalıştı diye onu doğrudan koda sabitlemeyin.

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

• herkese açık model ID'si
• API üzerinden kullanılabilir olup olmadığı
• desteklenen girdi modu
• prompt ve parametre beklentileri
• Files API gerekip gerekmediği
• kredi davranışı ve hazır olma 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 metin girdisiyle çalışabiliyorsa ilk sürümü yalnızca metinle sınırlı 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 temizleme adımından kimin sorumlu olduğu
• yükleme başarısız olduğunda ne olacağı
• dönen dosya verisinin 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 üretim düğmesinin arkasına saklanmasını önler.

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

Görsel, video ve ses üretimi için normal kalıp şudur:

1. model ID'sini, promptu ve desteklenen parametreleri hazırlayın
2. güvenli yeniden denemeler için idempotency key ekleyin
3. üretim uç noktası üzerinden gönderin
4. herkese açık görev ID'sini kaydedin
5. görev terminal duruma ulaşana kadar durumu yoklayın

İstek biçimi 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 durumlar 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: Sohbet Modelleri İçin Chat API Kullanın

Chat modelleri üretim uç noktasını değil, Chat API kullanmalıdır.

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

• sohbet turları API tarafından oluşturulan oturumlara ait olabilir
• akışsız yanıtlar ve SSE akışı farklı kullanıcı deneyimleri yaratır
• görsel ekleri Files API'den gelen dosya ID'lerini kullanır
• kredi mutabakatı normal eşzamansız medya görevi yerine sohbet turunu izler

Ürününüz kendi arayüzünde asistan 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: Yoklama ile Başlayın, Sonra Webhooks Ekleyin

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

Şu durumlarda API Webhooks ekleyin:

• üründe çok sayıda eşzamansız iş vardır
• bekleyen istemciler doğrudan yoklama yapmamalıdır
• aşağı akış sistemleri imzalı tamamlanma olayları gerektirir
• yeniden deneme ve yinelenen olay işleme zaten tasarlanmıştır

Webhook alıcıları sade ve katı olmalıdır: imzayı doğrulayın, yinelenmeye dayanıklı olayları kabul edin, tek ürün kaydını güncelleyin ve yalnızca güvenli olanları günlüğe yazı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 anahtarının hangi hesaba ait olduğu
• hangi iş akışının kredi tüketebileceği
• krediler çok düşük olduğunda ne olacağı
• başarısız üretim durumlarının nasıl açıklanacağı
• kredi ve faturalama soruları için nereye yönlendirme yapılacağı

Kullanıcıya dönük cüzdan modeli için API Kredileri, Rivya'da Krediler ve Faturalama ve Rivya Kredileri, Paketleri ve Planları 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:

1. tek API anahtarı
2. seçilmiş tek görsel modeli
3. henüz dosya yükleme yok
4. tek üretim isteği
5. tek durum yoklama yolu
6. ürününüzde basit bir sonuç önizlemesi
7. net bir kredi hata mesajı

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 parametre kontrolleri
• ürün kaydınıza bağlı idempotency
• tamamlanma için imzalı webhook'lar
• asistan turları için Chat API
• sohbet canlı çıktı istediğinde sunucu tarafı olay akışı
• başarısız işler için yönetici veya destek görünümleri

Her ekleme gerçek bir ürün ihtiyacına yanıt vermelidir. Yalnızca demoyu 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 yalnızca Studio'ya özgü varsayımlar kullanmak
• dosya yüklemelerini sonradan düşünülen ayrıntı gibi ele almak
• idempotency olmadan üretim isteğini yeniden denemek
• eşzamansız üretim olması gereken işler için Chat API kullanmak
• sohbet turları için üretim uç noktası kullanmak
• tam API anahtarını, webhook gizli değerini veya geçici dosya ayrıntılarını günlüğe yazmak

En güvenli API iş akışı sahipliği, durumu ve hata ele almayı açıkça belirtir.

Sonra Nereye Gidilmeli

• Herkese açık API merkezi 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.
• Sohbet turları ve akışlı sohbet yanıtları için Chat API kullanın.
• Yoklama 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.