Trimite sarcini asincrone de generare Rivya API folosind modelul, promptul, parametrii, Idempotency-Key și câmpurile publice de răspuns.

Folosește POST /api/v1/generations pentru a trimite o sarcină asincronă de generare a unei imagini, a unui videoclip sau a unui material audio.

Pentru modelele de chat, folosește Chat API. POST /api/v1/generations nu creează sesiuni de chat sau mesaje ale asistentului.

Endpoint

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

Antete obligatorii:

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

Antet recomandat:

Idempotency-Key: your-unique-request-key

Corpul cererii

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

Câmpuri:

model: ID-ul public obligatoriu al modelului
prompt: textul promptului, obligatoriu pentru multe modele
params: obiect cu parametri specifici modelului
client_request_id: ID opțional de urmărire din sistemul tău

Citește Referința API pentru modele pentru valorile params specifice modelului.

Fișiere de referință în params

Pentru modelele care acceptă materiale de referință încărcate, apelează mai întâi Files API. Apoi transmite rezultatul încărcării prin params ale modelului; nu adăuga un câmp de nivel superior files în cererea de generare.

Folosește params.referenceMediaItems pentru integrările noi:

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

Pentru intrările audio sau video care necesită verificarea duratei, include valoarea duration_token returnată de /api/v1/files sub formă durationToken în intrarea referenceMediaItems corespunzătoare.

Fiecare imagine de referință Image5 necesită valorile width, height, size_bytes și image_dimensions_token din răspunsul original Files API asociat modelului, transmise ca width, height, sizeBytes și imageDimensionsToken. Un token lipsă, expirat, necorespunzător sau inventat de client este respins înainte de crearea sarcinii și rezervarea creditelor. Layer Decomposition impune, de asemenea, exact o imagine care să respecte limitele geometrice documentate.

Grok Imagine Image 2.0 folosește aceeași barieră de validare pentru metadatele semnate ale imaginilor. Nu trimite niciun element de referință pentru generarea text-to-image; pentru editarea standard a imaginilor, trimite între unul și cinci elemente JPEG, PNG sau WebP, unice și semnate. Generarea text-to-image acceptă 1:1, 2:3, 3:2, 16:9 sau 9:16; editarea imaginilor acceptă suplimentar auto. Segment Map și Segment Edit nu sunt moduri apelabile prin Public API.

Fiecare videoclip de referință Video8 necesită valorile duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes și video_metadata_token din răspunsul original asociat modelului. Trimite-le ca durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes și videoMetadataToken. Ambii tokeni semnați sunt verificăți înainte de crearea sarcinii și rezervarea creditelor.

Wan 3.0 folosește trei valori seedance_scene care se exclud reciproc. text nu acceptă materiale încărcate; frames necesită o primă imagine și permite o ultimă imagine opțională; reference acceptă un set semnat de imagini, videoclipuri și fișiere audio, însă audio nu poate fi singurul material. Toate URL-urile de referință trebuie să provină din încărcări Files API originale, asociate modelului. Scurtăturile file-to-video și link-to-video rămân indisponibile.

Setează variant la standard sau prime, resolution la 480P, 720P sau 1080P, iar aspect_ratio la adaptive, 16:9, 4:3, 1:1, 3:4 sau 9:16. duration acceptă numere întregi de la 2 la 30 sau -1 pentru durată inteligentă; audio controlează sunetul creat de model, iar seed acceptă valori de la 0 la 2147483647. Promptul după eliminarea spațiilor suplimentare trebuie să conțină 1–20.000 de caractere.

Wan 3.0 Standard rezervă 8, 16 sau 32 de credite pentru fiecare secundă de rezultat solicitat la 480P, 720P sau 1080P. Prime rezervă 12,2, 25,2 sau 50,4 credite pe secundă. Rivya rotunjește în sus o singură dată rezervarea totală; durata inteligentă rezervă 30 de secunde. Consumul efectiv valid, cel mult egal cu rezerva, este decontat, iar diferența este returnată. Dacă valoarea consumului efectiv lipsește, este nevalidă sau depășește rezerva, această se păstrează și sarcină intră în reconciliere fără nicio debitare suplimentară ascunsă.

În modul de referință Wan 3.0, trimite cel mult 10 imagini, 5 videoclipuri și 5 clipuri audio. Fiecare clip video sau audio poate dura între 1 și 15 secunde, iar fiecare tip are o limită totală separată de 15 secunde. duration=-1 nu poate fi folosit cu un videoclip de referință; când există o intrare video, suma dintre secundele verificate ale videoclipului de intrare și secundele solicitate pentru rezultat nu trebuie să depășească 30.

Exemplu de cerere Video8 pentru o sarcină de sincronizare labială cu video și 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"
      }
    ]
  }
}

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": "A clean editorial product image on a soft studio background",
    "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: "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);

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

Răspuns

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

Salvează valoarea id și verifică periodic Starea generării. Dacă configurezi API Webhooks, Rivya poate trimite și un eveniment semnat generation.succeeded sau generation.failed atunci când sarcina ajunge într-o stare finală.

Idempotență

Folosește Idempotency-Key pentru reîncercări. Dacă aceeași cheie și același corp al cererii sunt retrimise, Rivya poate returna răspunsul public stocat în loc să creeze o sarcină duplicată.

Dacă aceeași cheie este refolosită cu o intrare diferită, API-ul returnează idempotency_conflict.

Creează o generare