model, prompt, params, Idempotency-Key, public response fields로 비동기 Rivya API generation jobs를 제출하세요.

비동기 이미지, 비디오, 오디오 generation job을 제출하려면 POST /api/v1/generations를 사용하세요.

chat models의 경우 Chat API를 사용하세요. POST /api/v1/generations는 chat sessions나 assistant messages를 만들지 않습니다.

Endpoint

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

Required headers:

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

Recommended header:

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

Fields:

model: 필수 public model ID
prompt: prompt text이며, 많은 model에서 필요합니다.
params: model-specific parameter object
client_request_id: 시스템에서 온 선택적 trace ID

model-specific params는 Model API Reference를 읽으세요.

Params의 Reference Files

업로드된 reference media를 받는 model의 경우 먼저 Files API를 호출하세요. 그런 다음 upload result를 model params를 통해 전달하고, generation request에 top-level files field를 추가하지 마세요.

새 integration에는 params.referenceMediaItems를 사용하세요.

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

duration verification이 필요한 audio 또는 video inputs의 경우 /api/v1/files가 반환한 duration_token을 관련 referenceMediaItems entry의 durationToken으로 포함하세요.

curl Example

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 Example

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 Example

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

Response

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

id를 저장하고 Generation Status를 poll하세요. API Webhooks를 구성하면 Rivya는 task가 terminal state에 도달했을 때 서명된 generation.succeeded 또는 generation.failed event도 보낼 수 있습니다.

Idempotency

retry에는 Idempotency-Key를 사용하세요. 같은 key와 같은 request body가 replay되면 Rivya는 duplicate task를 만들지 않고 저장된 public response를 반환할 수 있습니다.

같은 key를 다른 input과 함께 재사용하면 API는 idempotency_conflict를 반환합니다.

Generation 만들기