Hantar tugasan penjanaan Rivya API tak segerak dengan model, prompt, params, Idempotency-Key, dan medan respons awam.

Gunakan POST /api/v1/generations untuk menghantar tugasan penjanaan imej, video, atau audio tak segerak.

Untuk model sembang, gunakan Chat API. POST /api/v1/generations tidak mencipta sesi sembang atau mesej pembantu.

Titik akhir

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

Pengepala yang diperlukan:

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

Pengepala yang disyorkan:

Idempotency-Key: your-unique-request-key

Badan permintaan

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

Medan:

model: ID model awam yang diperlukan
prompt: teks prompt, diperlukan oleh banyak model
params: objek parameter khusus model
client_request_id: ID penjejakan pilihan daripada sistem anda

Baca Rujukan API Model untuk params khusus model.

Fail rujukan dalam params

Untuk model yang menerima media rujukan yang dimuat naik, panggil Files API dahulu. Kemudian masukkan hasil muat naik melalui params model; jangan tambah medan files peringkat atas pada permintaan penjanaan.

Gunakan params.referenceMediaItems untuk integrasi baharu:

{
  "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 memerlukan pengesahan tempoh, sertakan duration_token yang dikembalikan oleh /api/v1/files sebagai durationToken pada entri referenceMediaItems yang berkaitan.

Setiap imej rujukan Image5 memerlukan width, height, size_bytes, dan image_dimensions_token daripada respons asal Files API yang terikat pada model, dihantar sebagai width, height, sizeBytes, dan imageDimensionsToken. Token yang tiada, tamat tempoh, tidak sepadan, atau direka oleh klien akan ditolak sebelum tugasan dicipta dan kredit ditempah. Layer Decomposition turut memerlukan tepat satu imej dalam had geometri yang didokumenkan.

Grok Imagine Image 2.0 menggunakan sempadan metadata imej bertandatangan yang sama. Jangan hantar sebarang item rujukan untuk teks kepada imej; bagi penyuntingan imej standard, hantar 1–5 item JPEG, PNG atau WebP unik yang bertandatangan. Teks kepada imej menerima 1:1, 2:3, 3:2, 16:9 atau 9:16; penyuntingan imej turut menerima auto. Segment Map dan Segment Edit bukan mod Public API yang boleh dipanggil.

Setiap video rujukan Video8 memerlukan duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token daripada respons asal yang terikat pada model. Hantarnya sebagai durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes, dan videoMetadataToken. Kedua-dua token bertandatangan disahkan sebelum tugasan dicipta dan kredit ditempah.

Wan 3.0 menggunakan tiga nilai seedance_scene yang saling eksklusif. text tidak menerima media yang dimuat naik; frames memerlukan imej pertama dan membenarkan satu imej terakhir pilihan; reference menerima himpunan imej, video, dan audio bertandatangan, tetapi audio tidak boleh menjadi satu-satunya media. Semua URL rujukan mesti datang daripada muat naik Files API asal yang terikat pada model. Pintasan fail kepada video dan pautan kepada video kekal tidak tersedia.

Tetapkan variant kepada standard atau prime, resolution kepada 480P, 720P, atau 1080P, dan aspect_ratio kepada adaptive, 16:9, 4:3, 1:1, 3:4, atau 9:16. duration menerima nombor bulat dari 2 hingga 30, atau -1 untuk tempoh pintar; audio mengawal audio yang dicipta model dan seed menerima nilai dari 0 hingga 2147483647. Prompt yang telah dibuang ruang di hujungnya mesti mengandungi 1–20,000 aksara.

Wan 3.0 Standard menempah 8, 16, atau 32 kredit bagi setiap saat hasil yang diminta pada 480P, 720P, atau 1080P. Prime menempah 12.2, 25.2, atau 50.4 kredit sesaat. Rivya membundarkan jumlah tempahan ke atas sekali sahaja; tempoh pintar menempah 30 saat. Penggunaan sebenar yang sah dan tidak melebihi tempahan akan diselesaikan serta perbezaannya dipulangkan. Penggunaan sebenar yang tiada, tidak sah, atau lebih tinggi mengekalkan tempahan dan memasuki penyelarasan tanpa caj tambahan tersembunyi.

Dalam mod rujukan Wan 3.0, hantar paling banyak 10 imej, 5 video, dan 5 klip audio. Setiap klip video dan audio boleh berlangsung dari 1 hingga 15 saat dan setiap jenis mempunyai had jumlah 15 saat yang berasingan. duration=-1 tidak boleh digunakan bersama video rujukan; apabila ada input video, jumlah saat video input yang disahkan dan saat hasil yang diminta tidak boleh melebihi 30.

Contoh permintaan Video8 untuk tugasan penyegerakan bibir 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 buat semakan berkala pada Status Penjanaan. Jika anda mengkonfigurasi API Webhooks, Rivya juga boleh menghantar peristiwa generation.succeeded atau generation.failed yang bertandatangan apabila tugasan mencapai keadaan akhir.

Idempotensi

Gunakan Idempotency-Key untuk percubaan semula. Jika kunci dan badan permintaan yang sama dihantar semula, Rivya boleh mengembalikan respons awam yang disimpan dan bukannya mencipta tugasan pendua.

Jika kunci yang sama digunakan semula dengan input berbeza, API mengembalikan idempotency_conflict.

Cipta Penjanaan