Kirim pekerjaan generasi asinkron Rivya API dengan model, prompt, params, Idempotency-Key, dan field respons publik.

Gunakan POST /api/v1/generations untuk mengirim pekerjaan generasi gambar, video, atau audio asinkron.

Untuk model chat, gunakan Chat API. POST /api/v1/generations tidak membuat session chat atau pesan assistant.

Endpoint

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

Header wajib:

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

Header yang disarankan:

Idempotency-Key: your-unique-request-key

Isi request

{
  "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"
}

Field:

model: ID model publik yang wajib diisi
prompt: teks prompt, dibutuhkan oleh banyak model
params: objek parameter spesifik model
client_request_id: ID pelacakan opsional dari sistem Anda

Baca Referensi API Model untuk params spesifik model.

Untuk model yang menerima media referensi yang diunggah, panggil Files API terlebih dahulu. Lalu kirim hasil upload melalui params model; jangan tambahkan field files tingkat atas ke request generasi.

Gunakan params.referenceMediaItems untuk integrasi baru:

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

Untuk input audio atau video yang membutuhkan verifikasi durasi, sertakan duration_token yang dikembalikan oleh /api/v1/files sebagai durationToken pada entry referenceMediaItems terkait.

Contoh curl

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"
    }
  }'

Contoh JavaScript

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);

Contoh Python

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"])

Respons

{
  "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
}

Simpan id dan lakukan polling Status Generasi. Jika Anda mengonfigurasi API Webhooks, Rivya juga dapat mengirim event generation.succeeded atau generation.failed bertanda tangan saat tugas mencapai status terminal.

Idempotensi

Gunakan Idempotency-Key untuk retry. Jika key yang sama dan request body yang sama diputar ulang, Rivya dapat mengembalikan respons publik yang tersimpan alih-alih membuat tugas duplikat.

Jika key yang sama dipakai ulang dengan input berbeda, API mengembalikan idempotency_conflict.

Membuat Generasi