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.

Referenzdateien in 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-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"
      }
    ]
  }
}

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

Jedes Image5-Referenzbild benötigt width, height, size_bytes und image_dimensions_token aus der ursprünglichen modellgebundenen Files-API-Antwort. Sende sie als width, height, sizeBytes und imageDimensionsToken. Ein fehlender, abgelaufener, zu anderen Daten gehörender oder vom Client erfundener Token wird vor Task-Erstellung und Credit-Reservierung abgelehnt. Layer Decomposition verlangt zusätzlich genau ein Bild innerhalb der dokumentierten Geometriegrenzen.

Grok Imagine Image 2.0 verwendet denselben Vertrag für signierte Bildmetadaten. Sende für Text-zu-Bild keine Referenzeinträge; für die standardmäßige Bildbearbeitung sind 1–5 eindeutige, signierte JPEG-, PNG- oder WebP-Einträge erforderlich. Text-zu-Bild akzeptiert 1:1, 2:3, 3:2, 16:9 oder 9:16; bei der Bildbearbeitung ist zusätzlich auto zulässig. Segment Map und Segment Edit sind keine über die Public API aufrufbaren Modi.

Jedes Video8-Referenzvideo benötigt duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes und video_metadata_token aus der ursprünglichen modellgebundenen Antwort. Sende sie als durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes und videoMetadataToken. Beide signierten Token werden vor Task-Erstellung und Credit-Reservierung geprüft.

Wan 3.0 verwendet drei sich gegenseitig ausschließende seedance_scene-Werte. text akzeptiert keine hochgeladenen Medien; frames erfordert ein erstes Bild und erlaubt ein optionales letztes Bild; reference akzeptiert ein signiertes Bündel aus Bildern, Videos und Audio, Audio darf jedoch nicht das einzige Medium sein. Alle Referenz-URLs müssen aus ursprünglichen modellgebundenen Files-API-Uploads stammen. Datei-zu-Video- und Link-zu-Video-Kurzpfade bleiben nicht verfügbar.

Setze variant auf standard oder prime, resolution auf 480P, 720P oder 1080P und aspect_ratio auf adaptive, 16:9, 4:3, 1:1, 3:4 oder 9:16. duration akzeptiert ganze Zahlen von 2 bis 30 oder -1 für intelligente Dauer; audio steuert modellgeneriertes Audio und seed akzeptiert 0 bis 2147483647. Der bereinigte Prompt muss 1–20.000 Zeichen enthalten.

Wan 3.0 Standard reserviert bei 480P, 720P oder 1080P jeweils 8, 16 oder 32 Credits pro angeforderter Ausgabesekunde. Prime reserviert 12,2, 25,2 oder 50,4 Credits pro Sekunde. Rivya rundet die kombinierte Reservierung einmal auf; intelligente Dauer reserviert 30 Sekunden. Eine gültige tatsächliche Nutzung bis zur Reservierung wird abgerechnet und die Differenz erstattet. Fehlende, ungültige oder höhere tatsächliche Nutzung behält die Reservierung bei und wechselt in die Abstimmung, ohne eine versteckte zusätzliche Abbuchung.

Sende im Wan-3.0-Referenzmodus höchstens 10 Bilder, 5 Videos und 5 Audioclips. Video- und Audioclips dauern jeweils 1–15 Sekunden und haben je Medienart eine getrennte Gesamtdauergrenze von 15 Sekunden. duration=-1 ist mit Referenzvideo nicht zulässig; bei Videoeingabe dürfen verifizierte Eingabevideosekunden plus angeforderte Ausgabesekunden 30 nicht überschreiten.

Beispiel einer Video8-Anfrage für eine Lippensynchronisationsaufgabe mit Video und Audio:

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