ส่งงาน generation แบบ asynchronous ผ่าน Rivya API พร้อม model, prompt, params, Idempotency-Key และฟิลด์ response สาธารณะ

ใช้ POST /api/v1/generations เพื่อส่งงานสร้างภาพ วิดีโอ หรือเสียงแบบ asynchronous

สำหรับโมเดล chat ให้ใช้ Chat API POST /api/v1/generations จะไม่สร้าง chat sessions หรือ assistant messages

Endpoint ของ API

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

headers ที่จำเป็น:

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

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 ที่หลายโมเดลต้องใช้
params: object parameter เฉพาะโมเดล
client_request_id: trace ID จากระบบของคุณ แบบเลือกใส่ได้

อ่าน Model API Reference สำหรับ params เฉพาะโมเดล

Reference Files ใน Params

สำหรับโมเดลที่รับ uploaded reference media ให้เรียก Files API ก่อน จากนั้นส่งผลลัพธ์ upload ผ่าน params ของโมเดล อย่าเพิ่ม field files ระดับบนสุดใน generation request

ใช้ params.referenceMediaItems สำหรับ integrations ใหม่:

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

สำหรับ input แบบ audio หรือ video ที่ต้องตรวจ duration ให้ใส่ duration_token ที่ /api/v1/files คืนมาเป็น durationToken ในรายการ referenceMediaItems ที่เกี่ยวข้อง

ตัวอย่าง 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"
    }
  }'

ตัวอย่าง 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);

ตัวอย่าง 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"])

Response ของ API

{
  "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 แล้ว poll สถานะงาน Generation หากคุณตั้งค่า API Webhooks Rivya สามารถส่ง event generation.succeeded หรือ generation.failed แบบลงลายเซ็นเมื่อ task เข้าสู่ terminal state ได้ด้วย

Idempotency เพื่อป้องกันคำขอซ้ำ

ใช้ Idempotency-Key สำหรับการลองใหม่ หาก key เดิมและ request body เดิมถูก replay Rivya สามารถคืน public response ที่บันทึกไว้แทนการสร้าง task ซ้ำ

หาก key เดิมถูกใช้ซ้ำกับ input ที่ต่างกัน API จะคืน idempotency_conflict

สร้างงาน Generation