Trimite joburi asincrone de generare Rivya API cu model, prompt, params, Idempotency-Key si campuri publice de raspuns.

Foloseste POST /api/v1/generations pentru a trimite un job asincron de generare imagine, video sau audio.

Pentru modele de chat, foloseste Chat API. POST /api/v1/generations nu creeaza sesiuni de chat sau mesaje de asistent.

Endpoint

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

Headere necesare:

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

Header recomandat:

Idempotency-Key: your-unique-request-key

Body-ul cererii

{
  "model": "z-image",
  "prompt": "O imagine editoriala curata de produs pe un fundal moale de studio",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

Campuri:

model: ID public de model, obligatoriu
prompt: textul promptului, necesar pentru multe modele
params: obiect de parametri specifici modelului
client_request_id: ID optional de trasabilitate din sistemul tau

Citeste Referinta API pentru modele pentru params specifice modelului.

Fisiere de referinta in params

Pentru modelele care accepta media de referinta incarcata, apeleaza mai intai Files API. Apoi trimite rezultatul incarcarii prin params ale modelului; nu adauga un camp top-level files in cererea de generare.

Foloseste params.referenceMediaItems pentru integrari noi:

{
  "model": "nano-banana-2",
  "prompt": "Restilizeaza aceasta fotografie de produs pentru o pagina de catalog editorial curata",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  }
}

Pentru inputuri audio sau video care necesita verificarea duratei, include duration_token returnat de /api/v1/files ca durationToken in intrarea referenceMediaItems asociata.

Exemplu 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": "O imagine editoriala curata de produs pe un fundal moale de studio",
    "params": {
      "aspect_ratio": "1:1"
    }
  }'

Exemplu 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: "O imagine editoriala curata de produs pe un fundal moale de studio",
    params: { aspect_ratio: "1:1" }
  })
});

const generation = await response.json();
console.log(generation.id, generation.status);

Exemplu 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": "O imagine editoriala curata de produs pe un fundal moale de studio",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

generation = response.json()
print(generation["id"], generation["status"])

Raspuns

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

Salveaza id si interogheaza Statusul generarii. Daca configurezi API Webhooks, Rivya poate trimite si un eveniment semnat generation.succeeded sau generation.failed atunci cand sarcina ajunge intr-o stare terminala.

Idempotenta

Foloseste Idempotency-Key pentru reincercari. Daca aceeasi cheie si acelasi body al cererii sunt reluate, Rivya poate returna raspunsul public stocat in loc sa creeze o sarcina duplicata.

Daca aceeasi cheie este refolosita cu input diferit, API-ul returneaza idempotency_conflict.

Creeaza o generare