Invia job asincroni di generazione Rivya API con model, prompt, params, Idempotency-Key e campi di risposta pubblici.

Usa POST /api/v1/generations per inviare un job asincrono di generazione immagine, video o audio.

Per i modelli chat, usa Chat API. POST /api/v1/generations non crea sessioni chat o messaggi assistant.

Endpoint

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

Header richiesti:

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

Header consigliato:

Idempotency-Key: your-unique-request-key

Body della richiesta

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

Campi:

model: ID pubblico del modello, obbligatorio
prompt: testo del prompt, richiesto da molti modelli
params: oggetto di parametri specifico per modello
client_request_id: ID di tracciamento opzionale dal tuo sistema

Leggi riferimento API dei modelli per i params specifici del modello.

File di riferimento nei params

Per i modelli che accettano media di riferimento caricati, chiama prima Files API. Poi passa il risultato dell'upload tramite i params del modello; non aggiungere un campo files al livello principale nella richiesta di generazione.

Usa params.referenceMediaItems per nuove integrazioni:

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

Per input audio o video che richiedono verifica della durata, includi il duration_token restituito da /api/v1/files come durationToken nella voce referenceMediaItems correlata.

Ogni immagine di riferimento Image5 richiede width, height, size_bytes e image_dimensions_token della risposta originale di Files API associata al modello, inviati come width, height, sizeBytes e imageDimensionsToken. Un token mancante, scaduto, non corrispondente o inventato dal client causa un errore prima della creazione del task e della prenotazione dei crediti. Layer Decomposition richiede inoltre esattamente un'immagine entro i limiti geometrici documentati.

Grok Imagine Image 2.0 applica gli stessi requisiti di validazione dei metadati immagine firmati. Non inviare elementi di riferimento per la generazione da testo a immagine; per l'editing standard delle immagini, invia da una a cinque immagini di riferimento JPEG, PNG o WebP, firmate e distinte. La generazione da testo a immagine accetta 1:1, 2:3, 3:2, 16:9 o 9:16; l'editing delle immagini accetta anche auto. Segment Map e Segment Edit non sono modalità richiamabili tramite Public API.

Ogni video di riferimento Video8 richiede duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token della risposta originale associata al modello. Inviali come durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes e videoMetadataToken. Entrambi i token firmati vengono verificati prima della creazione del task e della prenotazione dei crediti.

Wan 3.0 usa tre valori di seedance_scene mutuamente esclusivi. text non accetta media caricati; frames richiede una prima immagine e consente un'ultima immagine opzionale; reference accetta un insieme firmato di immagini, video e audio, ma l'audio non può essere l'unico media. Tutti gli URL di riferimento devono provenire da upload originali di Files API associati al modello. Le scorciatoie da file a video e da link a video restano non disponibili.

Imposta variant su standard o prime, resolution su 480P, 720P o 1080P e aspect_ratio su adaptive, 16:9, 4:3, 1:1, 3:4 o 9:16. duration accetta numeri interi da 2 a 30 oppure -1 per la durata intelligente; audio controlla l'audio generato dal modello e seed accetta valori da 0 a 2147483647. Dopo aver rimosso gli spazi iniziali e finali, il prompt deve contenere da 1 a 20.000 caratteri.

Wan 3.0 Standard prenota 8, 16 o 32 crediti per ogni secondo di output richiesto a 480P, 720P o 1080P. Prime prenota 12,2, 25,2 o 50,4 crediti al secondo. Rivya arrotonda per eccesso una sola volta la prenotazione complessiva; la durata intelligente prenota 30 secondi. Quando il consumo effettivo è valido e non supera la prenotazione, la contabilizzazione si conclude e la differenza viene rimborsata. Se il consumo effettivo è assente, non valido o superiore, la prenotazione viene mantenuta e la richiesta passa alla riconciliazione, senza addebiti supplementari nascosti.

Nella modalità riferimento di Wan 3.0, invia al massimo 10 immagini, 5 video e 5 clip audio. Ogni video o clip audio deve durare da 1 a 15 secondi e ogni tipo ha un proprio limite complessivo di 15 secondi. duration=-1 non può essere usato con un video di riferimento; con un video in input, i secondi verificati del video in input più i secondi di output richiesti non possono superare 30.

Esempio di richiesta Video8 per un task di sincronizzazione labiale con video e 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"
      }
    ]
  }
}

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

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

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

Risposta

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

Salva l'id e fai polling di stato generazione. Se configuri API Webhooks, Rivya può anche inviare un evento firmato generation.succeeded o generation.failed quando il task raggiunge uno stato terminale.

Idempotenza

Usa Idempotency-Key per i retry. Se vengono riprodotti la stessa chiave e lo stesso body della richiesta, Rivya può restituire la risposta pubblica salvata invece di creare un task duplicato.

Se la stessa chiave viene riutilizzata con input diverso, l'API restituisce idempotency_conflict.

Creare una generazione