Odesílejte asynchronní úlohy generování v Rivya API s modelem, promptem, params, Idempotency-Key a veřejnými poli odpovědi.

Použijte POST /api/v1/generations k odeslání asynchronní úlohy generování obrázku, videa nebo audia.

Pro chatové modely použijte Chat API. POST /api/v1/generations nevytváří chatové relace ani zprávy asistenta.

Koncový bod

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

Požadované hlavičky:

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

Doporučená hlavička:

Idempotency-Key: your-unique-request-key

Tělo požadavku

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

Pole:

model: povinné veřejné ID modelu
prompt: text promptu, který mnoho modelů vyžaduje
params: objekt parametrů specifických pro model
client_request_id: volitelné trasovací ID z vašeho systému

Modelově specifické params najdete v referenci modelového API.

Referenční soubory v params

U modelů, které přijímají nahraná referenční média, nejprve zavolejte Files API. Potom předejte výsledek nahrání přes modelové params; do požadavku na generování nepřidávejte pole files na nejvyšší úrovni.

U nových integrací použijte params.referenceMediaItems:

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

U audio nebo video vstupů, které vyžadují ověření délky, vložte duration_token vrácený z /api/v1/files jako durationToken do související položky referenceMediaItems.

Každý referenční obrázek pro Image5 vyžaduje width, height, size_bytes a image_dimensions_token z původní odpovědi Files API svázané s modelem, odeslané jako width, height, sizeBytes a imageDimensionsToken. Chybějící, vypršelý, neshodný nebo klientem vymyšlený token způsobí selhání ještě před vytvořením úlohy a rezervací kreditů. Layer Decomposition navíc vyžaduje přesně jeden obrázek v rámci zdokumentovaných geometrických limitů.

Grok Imagine Image 2.0 používá stejná pravidla pro podepsaná metadata obrázků. Pro převod textu na obrázek neposílejte žádné referenční položky; pro standardní úpravu obrázku odešlete jednu až pět jedinečných podepsaných položek JPEG, PNG nebo WebP. Převod textu na obrázek podporuje 1:1, 2:3, 3:2, 16:9 nebo 9:16; úprava obrázku navíc podporuje auto. Režimy Segment Map a Segment Edit nelze prostřednictvím Public API volat.

Každé referenční video pro Video8 vyžaduje duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes a video_metadata_token z původní odpovědi svázané s modelem. Odešlete je jako durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes a videoMetadataToken. Oba podepsané tokeny se ověřují před vytvořením úlohy a rezervací kreditů.

Wan 3.0 používá tři vzájemně výlučné hodnoty seedance_scene. text nepřijímá žádná nahraná média; frames vyžaduje jeden první obrázek a umožňuje jeden volitelný poslední obrázek; reference přijímá podepsanou sadu obrázků, videí a audia, ale audio nesmí být jediným médiem. Všechny referenční URL musí pocházet z původních nahrání přes Files API svázaných s modelem. Zkratky file-to-video a link-to-video zůstávají nedostupné.

Nastavte variant na standard nebo prime, resolution na 480P, 720P nebo 1080P a aspect_ratio na adaptive, 16:9, 4:3, 1:1, 3:4 nebo 9:16. duration přijímá celá čísla od 2 do 30 nebo -1 pro inteligentní délku; audio řídí audio vytvořené modelem a seed přijímá hodnoty od 0 do 2147483647. Prompt po odstranění nadbytečných mezer musí obsahovat 1–20 000 znaků.

Wan 3.0 Standard rezervuje 8, 16 nebo 32 kreditů za každou požadovanou sekundu výstupu v rozlišení 480P, 720P nebo 1080P. Prime rezervuje 12,2, 25,2 nebo 50,4 kreditu za sekundu. Rivya zaokrouhlí celkovou rezervaci nahoru pouze jednou; inteligentní délka rezervuje 30 sekund. Platná skutečná spotřeba, která nepřevyšuje rezervaci, se vypořádá a rozdíl se vrátí. Při chybějící, neplatné nebo vyšší skutečné spotřebě se rezervace ponechá a úloha přejde ke kontrole vypořádání bez skrytého dodatečného stržení.

V referenčním režimu Wan 3.0 odešlete nejvýše 10 obrázků, 5 videí a 5 zvukových klipů. Video i audio klipy mohou mít délku 1 až 15 sekund a každý druh má samostatný souhrnný limit 15 sekund. duration=-1 nelze použít s referenčním videem; při video vstupu nesmí součet ověřené délky vstupního videa a požadované délky výstupu překročit 30 sekund.

Příklad požadavku Video8 pro synchronizaci rtů s videem a audiem:

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

Příklad 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"
    }
  }'

Příklad JavaScriptu

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);

Příklad Pythonu

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

Odpověď

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

Uložte id a dotazujte stav generování. Pokud nastavíte API Webhooks, Rivya může také poslat podepsanou událost generation.succeeded nebo generation.failed, když úloha dosáhne koncového stavu.

Idempotence

Pro opakované pokusy používejte Idempotency-Key. Pokud se znovu odešle stejný klíč a stejné tělo požadavku, Rivya může vrátit uloženou veřejnou odpověď místo vytvoření duplicitní úlohy.

Pokud je stejný klíč znovu použit s jiným vstupem, API vrátí idempotency_conflict.

Vytvoření generování