Wysyłaj asynchroniczne zadania generowania Rivya API z modelem, promptem, params, Idempotency-Key i publicznymi polami odpowiedzi.

Użyj POST /api/v1/generations, aby wysłać asynchroniczne zadanie generowania obrazu, wideo albo audio.

Dla modeli czatu użyj Chat API. POST /api/v1/generations nie tworzy sesji czatu ani wiadomości asystenta.

Endpoint

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

Wymagane nagłówki:

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

Zalecany nagłówek:

Idempotency-Key: your-unique-request-key

Body Żądania

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

Pola:

model: wymagany publiczny ID modelu
prompt: tekst promptu, wymagany przez wiele modeli
params: obiekt parametrów specyficznych dla modelu
client_request_id: opcjonalny ID śledzenia z Twojego systemu

Przeczytaj Referencję modeli API, aby poznać params specyficzne dla modelu.

Pliki Referencyjne w Params

Dla modeli, które akceptują przesłane media referencyjne, najpierw wywołaj Files API. Następnie przekaż wynik uploadu przez params modelu; nie dodawaj pola files na najwyższym poziomie żądania generowania.

Dla nowych integracji używaj 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"
      }
    ]
  }
}

Dla wejść audio albo wideo, które wymagają weryfikacji czasu trwania, dołącz duration_token zwrócony przez /api/v1/files jako durationToken w powiązanym wpisie referenceMediaItems.

Każdy obraz referencyjny Image5 wymaga pól width, height, size_bytes i image_dimensions_token z pierwotnej odpowiedzi Files API powiązanej z modelem, wysłanych jako width, height, sizeBytes i imageDimensionsToken. Brakujący, wygasły, niezgodny albo wymyślony przez klienta token powoduje odrzucenie żądania przed utworzeniem zadania i zarezerwowaniem kredytów. Layer Decomposition dodatkowo wymaga dokładnie jednego obrazu mieszczącego się w udokumentowanych limitach geometrii.

Grok Imagine Image 2.0 stosuje te same zasady dotyczące podpisanych metadanych obrazu. Przy generowaniu obrazu na podstawie tekstu nie wysyłaj żadnych elementów referencyjnych; przy standardowej edycji obrazu wyślij od jednego do pięciu unikalnych, podpisanych obrazów referencyjnych w formacie JPEG, PNG lub WebP. Generowanie obrazu na podstawie tekstu akceptuje 1:1, 2:3, 3:2, 16:9 lub 9:16; edycja obrazu dodatkowo akceptuje auto. Segment Map i Segment Edit nie są dostępne jako tryby Public API.

Każdy referencyjny plik wideo Video8 wymaga pól duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes i video_metadata_token z pierwotnej odpowiedzi powiązanej z modelem. Wyślij je odpowiednio jako durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes i videoMetadataToken. Oba podpisane tokeny są weryfikowane przed utworzeniem zadania i zarezerwowaniem kredytów.

Wan 3.0 używa trzech wzajemnie wykluczających się wartości seedance_scene. text nie akceptuje przesłanych mediów; frames wymaga pierwszego obrazu i dopuszcza opcjonalny ostatni obraz; reference akceptuje podpisany zestaw obrazów, wideo i audio, ale audio nie może być jedynym medium. Wszystkie adresy URL referencji muszą pochodzić z pierwotnych uploadów Files API powiązanych z modelem. Skróty przekształcania pliku w wideo i linku w wideo pozostają niedostępne.

Ustaw variant na standard lub prime, resolution na 480P, 720P lub 1080P, a aspect_ratio na adaptive, 16:9, 4:3, 1:1, 3:4 lub 9:16. duration akceptuje liczby całkowite od 2 do 30 albo -1 dla inteligentnego czasu trwania; audio steruje dźwiękiem generowanym przez model, a seed przyjmuje wartości od 0 do 2147483647. Po usunięciu początkowych i końcowych spacji prompt musi mieć od 1 do 20 000 znaków.

Wan 3.0 Standard rezerwuje 8, 16 lub 32 kredyty za każdą żądaną sekundę wyjścia w 480P, 720P lub 1080P. Prime rezerwuje 12,2, 25,2 lub 50,4 kredytu na sekundę. Rivya zaokrągla łączną rezerwację w górę tylko raz; inteligentny czas trwania rezerwuje 30 sekund. Jeśli rzeczywiste użycie jest prawidłowe i nie przekracza rezerwacji, rozliczenie zostaje zakończone, a różnica zwrócona. Jeśli rzeczywiste użycie jest nieobecne, nieprawidłowe lub wyższe, rezerwacja zostaje utrzymana, a żądanie przechodzi do uzgodnienia bez ukrytego dodatkowego obciążenia.

W trybie referencyjnym Wan 3.0 wyślij maksymalnie 10 obrazów, 5 plików wideo i 5 klipów audio. Każdy plik wideo lub klip audio musi trwać 1–15 sekund, a każdy typ ma osobny łączny limit 15 sekund. Nie można używać duration=-1 z referencyjnym plikiem wideo; przy wejściu wideo suma zweryfikowanych sekund wideo wejściowego i żądanych sekund wyjścia nie może przekroczyć 30.

Przykład żądania Video8 dla zadania synchronizacji ruchu ust z wideo i dźwiękiem:

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

Przykład 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"
    }
  }'

Przykład 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);

Przykład 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"])

Odpowiedź

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

Zapisz id i odpytuj status generowania. Jeśli skonfigurujesz API Webhooks, Rivya może też wysłać podpisane zdarzenie generation.succeeded albo generation.failed, gdy zadanie osiągnie stan końcowy.

Idempotencja

Używaj Idempotency-Key przy ponowieniach. Jeśli ten sam klucz i ta sama treść żądania zostaną odtworzone, Rivya może zwrócić zapisaną publiczną odpowiedź zamiast tworzyć duplikat zadania.

Jeśli ten sam klucz zostanie ponownie użyty z innymi danymi wejściowymi, API zwraca idempotency_conflict.

Utwórz generowanie