Gửi job generation bất đồng bộ của Rivya API với model, prompt, params, Idempotency-Key và các trường phản hồi công khai.

Dùng POST /api/v1/generations để gửi một job generation hình ảnh, video hoặc âm thanh bất đồng bộ.

Với mô hình chat, hãy dùng Chat API. POST /api/v1/generations không tạo chat session hoặc assistant message.

Endpoint

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

Headers bắt buộc:

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

Header khuyến nghị:

Idempotency-Key: your-unique-request-key

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

Các trường:

model: public model ID bắt buộc
prompt: văn bản prompt, bắt buộc với nhiều mô hình
params: object tham số riêng theo mô hình
client_request_id: trace ID tùy chọn từ hệ thống của bạn

Đọc Tham chiếu API mô hình cho params riêng theo mô hình.

Với các mô hình chấp nhận media tham chiếu đã tải lên, trước tiên hãy gọi Files API. Sau đó truyền kết quả upload qua params của mô hình; đừng thêm trường files cấp cao nhất vào yêu cầu generation.

Dùng params.referenceMediaItems cho tích hợp mới:

{
  "model": "nano-banana-2",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  }
}

Với input âm thanh hoặc video cần xác minh thời lượng, hãy đưa duration_token được /api/v1/files trả về vào mục referenceMediaItems liên quan dưới dạng durationToken.

Ví dụ 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"
    }
  }'

Ví dụ 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);

Ví dụ 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"])

Phản hồi

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

Lưu id và poll Trạng thái generation. Nếu bạn cấu hình API Webhooks, Rivya cũng có thể gửi sự kiện generation.succeeded hoặc generation.failed có chữ ký khi tác vụ đạt trạng thái cuối.

Idempotency

Dùng Idempotency-Key cho retry. Nếu cùng key và cùng request body được replay, Rivya có thể trả về phản hồi công khai đã lưu thay vì tạo tác vụ trùng lặp.

Nếu cùng key được dùng lại với input khác, API trả về idempotency_conflict.

Tạo generation