Lähetä asynkronisia Rivya API -generointitöitä mallilla, promptilla, params-arvoilla, Idempotency-Key-headerilla ja julkisilla vastauskentillä.

Käytä POST /api/v1/generations -endpointtia asynkronisen kuva-, video- tai audiogenerointityön lähettämiseen.

Chat-malleille käytä Chat API:a. POST /api/v1/generations ei luo chat-istuntoja eikä assistant-viestejä.

Rajapintareitti

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

Vaaditut headerit:

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

Suositeltu header:

Idempotency-Key: your-unique-request-key

Pyynnön 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"
}

Kentät:

model: pakollinen julkinen mallitunnus
prompt: promptiteksti, jota monet mallit vaativat
params: mallikohtainen parametriobjekti
client_request_id: valinnainen trace ID omasta järjestelmästäsi

Lue mallien API-viite mallikohtaisista params-arvoista.

Referenssitiedostot params-kentissä

Malleille, jotka hyväksyvät ladattua referenssimediaa, kutsu ensin Files API:a. Anna sen jälkeen lataustulos mallin params-kenttien kautta; älä lisää ylätason files-kenttää generointipyyntöön.

Käytä uusissa integraatioissa params.referenceMediaItems-rakennetta:

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

Audio- tai videosyötteille, jotka vaativat keston tarkistusta, sisällytä duration_token, jonka /api/v1/files palauttaa, arvona durationToken liittyvään referenceMediaItems-kohteeseen.

Jokainen Image5-referenssikuva vaatii alkuperäisen malliin sidotun Files API -vastauksen width-, height-, size_bytes- ja image_dimensions_token-arvot, jotka lähetetään nimillä width, height, sizeBytes ja imageDimensionsToken. Puuttuva, vanhentunut, yhteensopimaton tai asiakkaan itse keksimä token hylätään ennen tehtävän luontia ja krediittien varaamista. Layer Decomposition vaatii lisäksi täsmälleen yhden kuvan dokumentoitujen geometriarajojen sisällä.

Grok Imagine Image 2.0 noudattaa samoja allekirjoitettujen kuvametatietojen vaatimuksia. Älä lähetä referenssikohteita tekstistä kuvaksi -tilassa; lähetä tavallista kuvankäsittelyä varten 1–5 yksilöllistä, allekirjoitettua JPEG-, PNG- tai WebP-kohdetta. Tekstistä kuvaksi -tila hyväksyy suhteet 1:1, 2:3, 3:2, 16:9 ja 9:16; kuvankäsittely hyväksyy lisäksi arvon auto. Segment Map- ja Segment Edit -tiloja ei voi kutsua Public API:n kautta.

Jokainen Video8-referenssivideo vaatii alkuperäisen malliin sidotun vastauksen duration_seconds-, duration_token-, video_width-, video_height-, frames_per_second-, video_bitrate_mbps-, video_file_size_bytes- ja video_metadata_token-arvot. Lähetä ne nimillä durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes ja videoMetadataToken. Molemmat allekirjoitetut tokenit tarkistetaan ennen tehtävän luontia ja krediittien varaamista.

Wan 3.0 käyttää kolmea toisensa poissulkevaa seedance_scene-arvoa. text ei hyväksy ladattua mediaa; frames vaatii ensimmäisen kuvan ja sallii yhden valinnaisen viimeisen kuvan; reference hyväksyy allekirjoitetun kuvia, videoita ja audiota sisältävän kokonaisuuden, mutta audio ei voi olla ainoa media. Kaikkien referenssi-URL-osoitteiden on tultava alkuperäisistä malliin sidotuista Files API -latauksista. Tiedostosta videoksi- ja linkistä videoksi -pikareitit eivät ole käytettävissä.

Aseta variant arvoksi standard tai prime, resolution arvoksi 480P, 720P tai 1080P ja aspect_ratio arvoksi adaptive, 16:9, 4:3, 1:1, 3:4 tai 9:16. duration hyväksyy kokonaisluvut väliltä 2–30 tai arvon -1 älykästä kestoa varten; audio ohjaa mallin luomaa audiota ja seed hyväksyy arvot 0–2147483647. Trimmatussa promptissa on oltava 1–20 000 merkkiä.

Wan 3.0 Standard varaa 8, 16 tai 32 krediittiä pyydettyä tulostesekuntia kohden tarkkuudella 480P, 720P tai 1080P. Prime varaa 12,2, 25,2 tai 50,4 krediittiä sekunnissa. Rivya pyöristää yhdistetyn varauksen ylöspäin kerran; älykäs kesto varaa 30 sekuntia. Kelvollinen todellinen käyttö, joka ei ylitä varausta, selvitetään ja erotus palautetaan. Jos todellinen käyttö puuttuu, on virheellinen tai ylittää varauksen, varaus säilytetään ja siirtyy täsmäytykseen ilman piilotettua lisäveloitusta.

Wan 3.0 -referenssitilassa voit lähettää enintään 10 kuvaa, 5 videota ja 5 audioklippiä. Video- ja audioklippien pituus voi olla 1–15 sekuntia, ja kummallakin tyypillä on erillinen 15 sekunnin kokonaisraja. duration=-1 ei ole käytettävissä referenssivideon kanssa; videosyötteen kanssa varmennettujen syötevideosekuntien ja pyydettyjen tulostesekuntien summa ei saa ylittää arvoa 30.

Esimerkki Video8-pyynnöstä videon ja audion huulisynkronointitehtävälle:

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

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-esimerkki

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-esimerkki

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

Vastaus

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

Tallenna id ja pollaa generoinnin tilaa. Jos määrität API-webhookit, Rivya voi myös lähettää allekirjoitetun generation.succeeded- tai generation.failed-tapahtuman, kun tehtävä saavuttaa päätetilan.

Idempotenssi

Käytä Idempotency-Key-headeria retryihin. Jos sama avain ja sama pyynnön body toistetaan, Rivya voi palauttaa tallennetun julkisen vastauksen kaksoistehtävän luomisen sijaan.

Jos samaa avainta käytetään uudelleen eri syötteellä, API palauttaa virheen idempotency_conflict.

Luo generointi