Crea una chiave API, scegli un modello, invia un job asincrono di generazione e manda un turno Chat API con streaming SSE opzionale.

Questo quickstart mostra il percorso sicuro più breve dalla configurazione dell'account a un job di generazione Rivya API, più il primo turno Chat API.

Usa chiavi placeholder nei documenti e negli esempi. Non incollare mai una chiave API reale in codice pubblico, screenshot, ticket o documenti condivisi.

1. Creare una chiave API

Apri impostazioni API Keys, crea una chiave, copia una volta il segreto completo e conservalo nel tuo ambiente lato server.

Scope iniziali consigliati:

models:read
generations:create
generations:read
files:create
files:read
credits:read
webhooks:manage
chat:create
chat:read

2. Confermare la Base URL

Usa la base URL API di produzione:

https://rivya.ai

Gli URL localhost servono solo per sviluppo locale. Gli esempi pubblici non dovrebbero usare secret locali.

3. Elencare i modelli

curl https://rivya.ai/api/v1/models

Usa il campo id della risposta come valore model quando crei una generazione.

4. Inviare una generazione

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "model": "z-image",
    "prompt": "A clean editorial product image on a soft studio background"
  }'

La risposta restituisce un ID pubblico del task. Salvalo così potrai fare polling dello stato più tardi.

5. Fare polling dello stato

curl https://rivya.ai/api/v1/generations/task_public_id \
  -H "Authorization: Bearer rvya_sk_..."

I valori di stato sono:

queued
processing
succeeded
failed

6. Controllare i crediti

curl https://rivya.ai/api/v1/credits \
  -H "Authorization: Bearer rvya_sk_..."

Usalo per confermare il saldo attuale dell'account prima o dopo i test.

7. Opzionale: aggiungere Webhooks

Se il tuo server può ricevere callback HTTPS firmati, crea un endpoint webhook:

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

Salva il signing_secret mostrato una sola volta nella risposta e verifica ogni delivery prima di fidarti del payload.

8. Opzionale: inviare un turno Chat

Per i modelli chat, chiama Chat API invece di POST /api/v1/generations:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-chat-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

Usa il session_id restituito per continuare la sessione creata via API. Gli allegati immagine devono fare riferimento a valori file_id della Files API.

Opzionale: usare la beta del TypeScript SDK

Le integrazioni TypeScript lato server possono usare la beta dell'SDK locale:

import { RivyaClient } from "@rivya/sdk";

const rivya = new RivyaClient({
  apiKey: process.env.RIVYA_API_KEY
});

const generation = await rivya.generations.create({
  model: "z-image",
  prompt: "A clean editorial product image on a soft studio background"
});

Leggi Rivya TypeScript SDK prima di adottarlo. L'SDK include supporto allo streaming Chat lato server nella beta privata.

Quickstart Rivya API