Hantar kerja generation Rivya API tak segerak dengan model, prompt, params, Idempotency-Key, dan medan respons awam.

Gunakan POST /api/v1/generations untuk menghantar kerja generation imej, video, atau audio tak segerak.

Untuk model chat, gunakan Chat API. POST /api/v1/generations tidak mencipta sesi chat atau mesej assistant.

Endpoint

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

Header diperlukan:

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

Header disarankan:

Idempotency-Key: your-unique-request-key

Request Body

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

Medan:

model: public model ID yang diperlukan
prompt: teks prompt, diperlukan oleh banyak model
params: objek parameter khusus model
client_request_id: trace ID pilihan daripada sistem anda

Baca Rujukan API Model untuk params khusus model.

Untuk model yang menerima media rujukan yang dimuat naik, panggil Files API dahulu. Kemudian hantar hasil muat naik melalui params model; jangan tambah medan files peringkat atas pada permintaan generation.

Gunakan params.referenceMediaItems untuk integrasi baharu:

{
  "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 memerlukan pengesahan durasi, sertakan duration_token yang dikembalikan oleh /api/v1/files sebagai durationToken pada entri referenceMediaItems berkaitan.

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 poll Status Generation. Jika anda mengkonfigurasi API Webhooks, Rivya juga boleh menghantar event generation.succeeded atau generation.failed yang ditandatangani apabila tugasan mencapai keadaan terminal.

Idempotency

Gunakan Idempotency-Key untuk retry. Jika key yang sama dan request body yang sama dimainkan semula, Rivya boleh mengembalikan respons awam tersimpan, bukan mencipta tugasan pendua.

Jika key yang sama digunakan semula dengan input berbeza, API mengembalikan idempotency_conflict.

Cipta Generation