Küldj be aszinkron Rivya API generálási feladatokat modellel, prompttal, params mezővel, Idempotency-Key headerrel és nyilvános válaszmezőkkel.

Használd a POST /api/v1/generations endpointot aszinkron kép-, videó- vagy hanggenerálási feladat beküldéséhez.

Chatmodellekhez használd a Chat API oldalt. A POST /api/v1/generations nem hoz létre chatmunkameneteket vagy asszisztensüzeneteket.

Endpoint

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

Szükséges headerek:

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

Ajánlott 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"
}

Mezők:

model: kötelező nyilvános modellazonosító
prompt: promptszöveg, sok modellnél kötelező
params: modell-specifikus paraméterobjektum
client_request_id: opcionális trace ID a saját rendszeredből

Modell-specifikus params mezőkhöz olvasd a Modell API referenciát.

Referenciafájlok a params mezőben

Azoknál a modelleknél, amelyek feltöltött referenciamédiát fogadnak, először hívd meg a Files API oldalt. Ezután add át a feltöltés eredményét a modell params mezőin keresztül; ne adj felső szintű files mezőt a generálási kéréshez.

Új integrációknál használd a params.referenceMediaItems mezőt:

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

Duration ellenőrzést igénylő hang- vagy videóbemeneteknél a duration_token értéket, amelyet a /api/v1/files ad vissza, durationToken néven add meg a kapcsolódó referenceMediaItems elemben.

Minden Image5 referenciaképhez szükség van az eredeti, modellhez kötött Files API-válasz width, height, size_bytes és image_dimensions_token értékére, amelyeket width, height, sizeBytes és imageDimensionsToken néven kell elküldeni. Hiányzó, lejárt, eltérő vagy a kliens által kitalált token esetén a kérés még a feladat létrehozása és a kreditek lefoglalása előtt meghiúsul. A Layer Decomposition ezenfelül pontosan egy, a dokumentált geometriai korlátoknak megfelelő képet követel meg.

A Grok Imagine Image 2.0 ugyanezt az aláírt képmetaadatokra vonatkozó biztonsági korlátot alkalmazza. Szövegből képgeneráláskor ne küldj referenciaelemet; normál képszerkesztéshez egy–öt egyedi, aláírt JPEG-, PNG- vagy WebP-elemet küldj. A szövegből képgenerálás az 1:1, 2:3, 3:2, 16:9 és 9:16 képarányt fogadja el; a képszerkesztés ezenfelül az auto értéket is. A Segment Map és a Segment Edit nem hívható meg a Public API-n keresztül.

Minden Video8 referenciavideóhoz szükség van az eredeti, modellhez kötött válasz duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes és video_metadata_token értékére. Küldd el őket durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes és videoMetadataToken néven. A rendszer mindkét aláírt tokent ellenőrzi a feladat létrehozása és a kreditek lefoglalása előtt.

A Wan 3.0 három, egymást kölcsönösen kizáró seedance_scene értéket használ. A text nem fogad feltöltött médiát; a frames egy első képet kötelezővé tesz, és egy opcionális utolsó képet engedélyez; a reference aláírt kép-, videó- és hangcsomagot fogad, de a hang nem lehet az egyetlen média. Minden referencia-URL-nek eredeti, modellhez kötött Files API-feltöltésből kell származnia. A file-to-video és link-to-video rövidítések továbbra sem érhetők el.

A variant értéke standard vagy prime, a resolution értéke 480P, 720P vagy 1080P, az aspect_ratio értéke pedig adaptive, 16:9, 4:3, 1:1, 3:4 vagy 9:16 lehet. A duration 2 és 30 közötti egész számot, illetve intelligens időtartamhoz -1 értéket fogad; az audio a modell által létrehozott hangot vezérli, a seed pedig 0 és 2147483647 közötti értéket fogad. A levágott promptnak 1–20 000 karaktert kell tartalmaznia.

A Wan 3.0 Standard a kért kimenet minden másodpercére 8, 16 vagy 32 kreditet foglal le 480P, 720P vagy 1080P felbontásban. A Prime másodpercenként 12,2, 25,2 vagy 50,4 kreditet foglal le. A Rivya a teljes foglalást csak egyszer kerekíti felfelé; az intelligens időtartam 30 másodpercet foglal le. A foglalást meg nem haladó, érvényes tényleges felhasználás elszámolásra kerül, a különbözetet pedig a rendszer visszatéríti. Hiányzó, érvénytelen vagy magasabb tényleges felhasználás esetén a foglalás megmarad, a feladat pedig egyeztetésre kerül rejtett további levonás nélkül.

A Wan 3.0 referencia módjában legfeljebb 10 képet, 5 videót és 5 hangklipet küldj. A videó- és hangklipek egyenként 1–15 másodpercesek lehetnek, és mindkét típus külön 15 másodperces összesített limittel rendelkezik. A duration=-1 nem használható referenciavideóval; videóbemenet esetén az ellenőrzött bemeneti videó másodperceinek és a kért kimenet másodperceinek összege nem haladhatja meg a 30-at.

Példa Video8 kérésre egy videó- és hangbemenetet használó szájszinkronizálási feladathoz:

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

curl példa

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 példa

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 példa

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

Válasz

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

Mentsd el az id értéket, és kérdezd le a Generálási állapot oldalon. Ha beállítod az API webhookokat, a Rivya aláírt generation.succeeded vagy generation.failed eseményt is küldhet, amikor a feladat végállapotba ér.

Idempotencia

Újrapróbálkozásokhoz használj Idempotency-Key headert. Ha ugyanazt a kulcsot és ugyanazt a request body-t játszod vissza, a Rivya a tárolt nyilvános választ adhatja vissza ahelyett, hogy duplikált feladatot hozna létre.

Ha ugyanazt a kulcsot más bemenettel használod újra, az API idempotency_conflict választ ad.

Generálás létrehozása