Kirim tugas pembuatan asinkron melalui Rivya API dengan model, prompt, `params`, `Idempotency-Key`, dan bidang respons publik.

Gunakan POST /api/v1/generations untuk mengirim pekerjaan generasi gambar, video, atau audio asinkron.

Untuk model chat, gunakan Chat API. POST /api/v1/generations tidak membuat session chat atau pesan assistant.

Endpoint

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

Header wajib:

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

Header yang disarankan:

Idempotency-Key: your-unique-request-key

Isi request

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

Field:

model: ID model publik yang wajib diisi
prompt: teks prompt, dibutuhkan oleh banyak model
params: objek parameter spesifik model
client_request_id: ID pelacakan opsional dari sistem Anda

Baca Referensi API Model untuk params spesifik model.

File Referensi Dalam Params

Untuk model yang menerima media referensi yang diunggah, panggil Files API terlebih dahulu. Lalu kirim hasil upload melalui params model; jangan tambahkan field files tingkat atas ke request generasi.

Gunakan params.referenceMediaItems untuk integrasi baru:

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

Untuk input audio atau video yang membutuhkan verifikasi durasi, sertakan duration_token yang dikembalikan oleh /api/v1/files sebagai durationToken pada entry referenceMediaItems terkait.

Setiap gambar referensi Image5 memerlukan width, height, size_bytes, dan image_dimensions_token dari respons Files API asli yang terikat ke model, lalu dikirim sebagai width, height, sizeBytes, dan imageDimensionsToken. Token yang hilang, kedaluwarsa, tidak cocok, atau dibuat sendiri oleh klien akan ditolak sebelum tugas dibuat dan credits direservasi. Layer Decomposition juga mengharuskan tepat satu gambar yang memenuhi batas geometrinya dalam dokumentasi.

Grok Imagine Image 2.0 mengikuti aturan validasi metadata gambar bertanda tangan yang sama. Jangan kirim item referensi untuk pembuatan gambar dari teks; untuk pengeditan gambar standar, kirim satu hingga lima item JPEG, PNG, atau WebP yang unik dan bertanda tangan. Pembuatan gambar dari teks menerima 1:1, 2:3, 3:2, 16:9, atau 9:16; pengeditan gambar juga menerima auto. Segment Map dan Segment Edit tidak dapat dipanggil melalui Public API.

Setiap video referensi Video8 memerlukan duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token dari respons asli yang terikat ke model. Kirim sebagai durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes, dan videoMetadataToken. Kedua token bertanda tangan diverifikasi sebelum tugas dibuat dan credits direservasi.

Wan 3.0 menggunakan tiga nilai seedance_scene yang saling eksklusif. Mode text tidak menerima media unggahan; frames memerlukan satu gambar pertama dan mengizinkan satu gambar terakhir opsional; reference menerima kumpulan gambar, video, dan audio bertanda tangan, tetapi audio tidak dapat menjadi satu-satunya media. Semua URL referensi harus berasal dari unggahan Files API asli yang terikat ke model. Pintasan file-to-video dan link-to-video tetap tidak tersedia.

Atur variant ke standard atau prime, resolution ke 480P, 720P, atau 1080P, dan aspect_ratio ke adaptive, 16:9, 4:3, 1:1, 3:4, atau 9:16. duration menerima bilangan bulat dari 2 hingga 30, atau -1 untuk durasi cerdas; audio mengontrol audio buatan model, dan seed menerima 0 hingga 2147483647. Prompt setelah dirapikan harus berisi 1–20.000 karakter.

Wan 3.0 Standard mereservasi 8, 16, atau 32 credits per detik output yang diminta pada 480P, 720P, atau 1080P. Prime mereservasi 12,2, 25,2, atau 50,4 credits per detik. Rivya membulatkan total reservasi ke atas satu kali; durasi cerdas mereservasi 30 detik. Pemakaian aktual yang valid dan tidak melebihi reservasi akan diselesaikan serta mengembalikan selisihnya. Jika pemakaian aktual hilang, tidak valid, atau lebih tinggi, reservasi dipertahankan dan masuk rekonsiliasi tanpa potongan tambahan tersembunyi.

Dalam mode referensi Wan 3.0, kirim paling banyak 10 gambar, 5 video, dan 5 klip audio. Setiap klip video dan audio berdurasi 1 hingga 15 detik, dan setiap jenis memiliki batas total terpisah sebesar 15 detik. duration=-1 tidak dapat digunakan bersama video referensi; jika ada input video, jumlah detik video input yang terverifikasi dan detik output yang diminta tidak boleh melebihi 30.

Contoh request Video8 untuk tugas sinkronisasi bibir dengan video dan 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"
      }
    ]
  }
}

Contoh 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"
    }
  }'

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

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

Respons

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

Simpan id dan lakukan polling Status Generasi. Jika Anda mengonfigurasi API Webhooks, Rivya juga dapat mengirim event generation.succeeded atau generation.failed bertanda tangan saat tugas mencapai status terminal.

Idempotensi

Gunakan Idempotency-Key untuk retry. Jika key yang sama dan request body yang sama diputar ulang, Rivya dapat mengembalikan respons publik yang tersimpan alih-alih membuat tugas duplikat.

Jika key yang sama dipakai ulang dengan input berbeda, API mengembalikan idempotency_conflict.

Membuat Generasi