Υποβάλετε ασύγχρονες εργασίες generation του Rivya API με model, prompt, params, Idempotency-Key και δημόσια πεδία απόκρισης.

Χρησιμοποιήστε POST /api/v1/generations για να υποβάλετε μια ασύγχρονη εργασία generation εικόνας, βίντεο ή ήχου.

Για μοντέλα chat, χρησιμοποιήστε το Chat API. Το POST /api/v1/generations δεν δημιουργεί chat sessions ή assistant messages.

Endpoint

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

Απαιτούμενα headers:

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

Προτεινόμενο 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"
}

Πεδία:

model: απαιτούμενο δημόσιο model ID
prompt: κείμενο προτροπής, απαιτείται από πολλά μοντέλα
params: αντικείμενο παραμέτρων ειδικό για το μοντέλο
client_request_id: προαιρετικό trace ID από το σύστημά σας

Διαβάστε την Αναφορά API μοντέλων για model-specific params.

Αρχεία αναφοράς μέσα σε params

Για μοντέλα που δέχονται ανεβασμένα μέσα αναφοράς, καλέστε πρώτα το Files API. Έπειτα περάστε το αποτέλεσμα ανεβάσματος μέσω των params του μοντέλου· μην προσθέτετε top-level πεδίο files στο αίτημα generation.

Χρησιμοποιήστε params.referenceMediaItems για νέες ενσωματώσεις:

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

Για εισόδους ήχου ή βίντεο που απαιτούν επαλήθευση διάρκειας, συμπεριλάβετε το duration_token που επιστρέφεται από το /api/v1/files ως durationToken στη σχετική καταχώρηση referenceMediaItems.

Παράδειγμα 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"
    }
  }'

Παράδειγμα 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);

Παράδειγμα 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"])

Απάντηση

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

Αποθηκεύστε το id και κάντε poll στην Κατάσταση generation. Αν διαμορφώσετε API Webhooks, το Rivya μπορεί επίσης να στείλει υπογεγραμμένο event generation.succeeded ή generation.failed όταν η εργασία φτάσει σε τελική κατάσταση.

Idempotency

Χρησιμοποιήστε Idempotency-Key για retries. Αν το ίδιο key και το ίδιο request body αναπαραχθούν, το Rivya μπορεί να επιστρέψει την αποθηκευμένη δημόσια απάντηση αντί να δημιουργήσει διπλή εργασία.

Αν το ίδιο key επαναχρησιμοποιηθεί με διαφορετικό input, το API επιστρέφει idempotency_conflict.

Δημιουργία generation