Reiche asynchrone Rivya API-Generation-Jobs mit model, prompt, params, Idempotency-Key und öffentlichen Response-Feldern ein.

Nutze POST /api/v1/generations, um einen asynchronen Bild-, Video- oder Audio-Generation-Job einzureichen.

Für Chat-Modelle nutze die Chat API. POST /api/v1/generations erstellt keine Chat-Sessions oder Assistant-Nachrichten.

Endpoint

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

Erforderliche Header:

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

Empfohlener Header:

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

Felder:

model: erforderliche öffentliche Modell-ID
prompt: Prompt-Text, von vielen Modellen verlangt
params: modellspezifisches Parameterobjekt
client_request_id: optionale Trace-ID aus deinem System

Lies die Modell-API-Referenz für modellspezifische params.

Für Modelle, die hochgeladene Referenzmedien akzeptieren, rufe zuerst die Files API auf. Übergib danach das Upload-Ergebnis über Modell-params; füge der Generation-Anfrage kein top-level Feld files hinzu.

Nutze params.referenceMediaItems für neue Integrationen:

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

Für Audio- oder Videoeingaben, die eine Duration-Prüfung erfordern, füge das von /api/v1/files zurückgegebene duration_token als durationToken im zugehörigen referenceMediaItems-Eintrag ein.

curl-Beispiel

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-Beispiel

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-Beispiel

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

Antwort

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

Speichere die id und frage den Generation-Status ab. Wenn du API Webhooks konfigurierst, kann Rivya außerdem ein signiertes Event generation.succeeded oder generation.failed senden, wenn der Task einen terminalen Zustand erreicht.

Idempotenz

Nutze Idempotency-Key für Retries. Wenn derselbe Key und derselbe Request Body erneut abgespielt werden, kann Rivya die gespeicherte öffentliche Antwort zurückgeben, statt einen doppelten Task zu erstellen.

Wenn derselbe Key mit anderem Input wiederverwendet wird, gibt die API idempotency_conflict zurück.

Generation erstellen