Model, prompt, params, Idempotency-Key ve public yanıt alanlarıyla asenkron Rivya API oluşturma işleri gönderin.

Asenkron bir görüntü, video veya ses oluşturma işi göndermek için POST /api/v1/generations kullanın.

Chat modelleri için Chat API kullanın. POST /api/v1/generations, chat oturumları veya asistan mesajları oluşturmaz.

Endpoint

POST https://rivya.ai/api/v1/generations

Gerekli header'lar:

Authorization: Bearer rvya_sk_...
Content-Type: application/json

Önerilen header:

Idempotency-Key: your-unique-request-key

İstek Gövdesi

{
  "model": "z-image",
  "prompt": "A clean editorial product image on a soft studio background",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

Alanlar:

model: gerekli public model ID'si
prompt: prompt metni, birçok model için gereklidir
params: modele özel parametre nesnesi
client_request_id: sisteminizden gelen isteğe bağlı trace ID

Modele özel params için Model API Referansı sayfasını okuyun.

Referans Dosyaları Params İçinde

Yüklenen referans medyayı kabul eden modeller için önce Files API çağırın. Sonra yükleme sonucunu model params üzerinden gönderin; oluşturma isteğine üst düzey files alanı eklemeyin.

Yeni entegrasyonlarda params.referenceMediaItems kullanın:

{
  "model": "nano-banana-2-lite",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024,
        "sizeBytes": 482314,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  }
}

Süre doğrulaması gerektiren ses veya video girdileri için /api/v1/files tarafından döndürülen duration_token değerini ilgili referenceMediaItems girdisinde durationToken olarak ekleyin.

Her Image5 referans görüntüsü, özgün modele bağlı Files API yanıtındaki width, height, size_bytes ve image_dimensions_token değerlerini sırasıyla width, height, sizeBytes ve imageDimensionsToken olarak göndermelidir. Eksik, süresi dolmuş, eşleşmeyen veya istemci tarafından uydurulmuş bir token; görev oluşturulmadan ve kredi ayrılmadan önce isteğin başarısız olmasına yol açar. Layer Decomposition ayrıca belgelenen geometri limitleri içinde tam olarak bir görüntü gerektirir.

Grok Imagine Image 2.0, aynı imzalı görüntü metadata doğrulamasına tabidir. Metinden görüntü oluşturma için hiçbir referans öğesi göndermeyin; standart görüntü düzenleme için bir ila beş benzersiz, imzalı JPEG, PNG veya WebP öğesi gönderin. Metinden görüntü oluşturma 1:1, 2:3, 3:2, 16:9 veya 9:16 oranlarını kabul eder; görüntü düzenleme ayrıca auto değerini kabul eder. Segment Map ve Segment Edit, Public API üzerinden çağrılamaz.

Her Video8 referans videosu, özgün modele bağlı yanıttaki duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes ve video_metadata_token değerlerini gerektirir. Bunları sırasıyla durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes ve videoMetadataToken olarak gönderin. Her iki imzalı token da görev oluşturulmadan ve kredi ayrılmadan önce doğrulanır.

Wan 3.0, birbirini dışlayan üç seedance_scene değeri kullanır. text yüklenen medyayı kabul etmez; frames bir ilk görüntüyü zorunlu tutar ve isteğe bağlı bir son görüntüye izin verir; reference imzalı görüntü, video ve ses paketini kabul eder, ancak ses tek medya olamaz. Tüm referans URL'leri özgün, modele bağlı Files API yüklemelerinden gelmelidir. Dosyadan videoya ve bağlantıdan videoya kısayollar kullanılamaz.

variant değerini standard veya prime, resolution değerini 480P, 720P veya 1080P, aspect_ratio değerini de adaptive, 16:9, 4:3, 1:1, 3:4 veya 9:16 olarak ayarlayın. duration, 2 ile 30 arasındaki tam sayıları veya akıllı süre için -1 değerini kabul eder; audio modelin oluşturduğu sesi denetler ve seed değeri 0 ile 2147483647 arasında olabilir. Baştaki ve sondaki boşluklar kaldırıldıktan sonra prompt 1–20.000 karakter içermelidir.

Wan 3.0 Standard, 480P, 720P veya 1080P için istenen her çıktı saniyesi başına 8, 16 veya 32 kredi ayırır. Prime saniye başına 12,2, 25,2 veya 50,4 kredi ayırır. Rivya birleşik rezervi yalnızca bir kez yukarı yuvarlar; akıllı süre 30 saniye ayırır. Geçerli ve rezervi aşmayan gerçek kullanımda hesaplaşma tamamlanır ve fark iade edilir. Gerçek kullanım eksik, geçersiz veya daha yüksekse rezerv korunur ve istek mutabakat sürecine girer; gizli ek kesinti yapılmaz.

Wan 3.0 referans modunda en fazla 10 görüntü, 5 video ve 5 ses klibi gönderin. Her video veya ses klibi 1–15 saniye olmalı ve her tür için ayrı bir toplam 15 saniye sınırı uygulanmalıdır. duration=-1 referans videosuyla kullanılamaz; video girdisi olduğunda doğrulanmış girdi videosu saniyeleri ile istenen çıktı saniyelerinin toplamı 30'u aşamaz.

Video ile ses kullanan bir dudak senkronizasyonu görevi için örnek Video8 isteği:

{
  "model": "volcengine-video-lip-sync",
  "prompt": "",
  "params": {
    "mode": "lite",
    "separate_vocal": "false",
    "open_scenedet": "false",
    "referenceMediaItems": [
      {
        "url": "https://.../source.mov",
        "kind": "video",
        "name": "source.mov",
        "mimeType": "video/quicktime",
        "durationSeconds": 12.4,
        "durationToken": "duration_token_from_files_api",
        "width": 1920,
        "height": 1080,
        "framesPerSecond": 30,
        "videoBitrateMbps": 8.5,
        "sizeBytes": 26214400,
        "videoMetadataToken": "video_metadata_token_from_files_api"
      },
      {
        "url": "https://.../dialogue.wav",
        "kind": "audio",
        "name": "dialogue.wav",
        "mimeType": "audio/wav",
        "durationSeconds": 12.4,
        "durationToken": "audio_duration_token_from_files_api"
      }
    ]
  }
}

curl Örneği

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-preview-001" \
  -d '{
    "model": "z-image",
    "prompt": "A clean editorial product image on a soft studio background",
    "params": {
      "aspect_ratio": "1:1"
    }
  }'

JavaScript Örneği

const response = await fetch("https://rivya.ai/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVYA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "product-preview-001"
  },
  body: JSON.stringify({
    model: "z-image",
    prompt: "A clean editorial product image on a soft studio background",
    params: { aspect_ratio: "1:1" }
  })
});

const generation = await response.json();
console.log(generation.id, generation.status);

Python Örneği

import os
import requests

response = requests.post(
    "https://rivya.ai/api/v1/generations",
    headers={
        "Authorization": f"Bearer {os.environ['RIVYA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "product-preview-001",
    },
    json={
        "model": "z-image",
        "prompt": "A clean editorial product image on a soft studio background",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

generation = response.json()
print(generation["id"], generation["status"])

Yanıt

{
  "id": "task_public_id",
  "status": "queued",
  "model": "z-image",
  "reserved_credits": 1,
  "final_credits": 0,
  "created_at": "2026-05-10T00:00:00.000Z",
  "updated_at": "2026-05-10T00:00:00.000Z",
  "result": null,
  "error": null
}

id değerini kaydedin ve Oluşturma Durumu sayfasındaki akışla poll edin. API Webhooks yapılandırırsanız Rivya, görev terminal duruma ulaştığında imzalı bir generation.succeeded veya generation.failed olayı da gönderebilir.

İdempotency

Yeniden denemeler için Idempotency-Key kullanın. Aynı anahtar ve aynı istek gövdesi tekrar oynatılırsa Rivya yinelenen görev oluşturmak yerine saklanan public yanıtı döndürebilir.

Aynı anahtar farklı input ile yeniden kullanılırsa API idempotency_conflict döndürür.

Oluşturma İşi Başlatma