สร้าง API key, เลือกโมเดล, ส่งงาน generation แบบ asynchronous และส่ง Chat API turn พร้อม SSE streaming แบบเลือกใช้ได้

คู่มือเริ่มต้นนี้แสดงเส้นทางที่ปลอดภัยและสั้นที่สุดตั้งแต่การตั้งค่าบัญชีไปจนถึงงาน generation ผ่าน Rivya API หนึ่งงาน พร้อม Chat API turn แรก

ใช้ placeholder keys ใน docs และตัวอย่าง อย่าวาง API key จริงลงใน public code, ภาพหน้าจอ, ticket หรือเอกสารที่แชร์

1. สร้าง API Key

เปิด การตั้งค่า API Keys, สร้าง key, คัดลอก secret เต็มหนึ่งครั้ง แล้วเก็บไว้ใน environment ฝั่ง server ของคุณ

scopes แรกที่แนะนำ:

models:read
generations:create
generations:read
files:create
files:read
credits:read
webhooks:manage
chat:create
chat:read

2. ยืนยัน Base URL

ใช้ production API base URL:

https://rivya.ai

localhost URLs ใช้สำหรับ local development เท่านั้น public examples ไม่ควรใช้ local secrets

3. ดูรายการโมเดล

curl https://rivya.ai/api/v1/models

ใช้ field id จาก response เป็นค่า model เมื่อสร้าง generation

4. ส่ง Generation

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "model": "z-image",
    "prompt": "A clean editorial product image on a soft studio background"
  }'

response จะคืน public task ID ให้เก็บไว้เพื่อ poll status ภายหลัง

5. Poll Status

curl https://rivya.ai/api/v1/generations/task_public_id \
  -H "Authorization: Bearer rvya_sk_..."

status values คือ:

queued
processing
succeeded
failed

6. ตรวจเครดิต

curl https://rivya.ai/api/v1/credits \
  -H "Authorization: Bearer rvya_sk_..."

ใช้สิ่งนี้เพื่อยืนยันยอดคงเหลือของบัญชีปัจจุบันก่อนหรือหลังการทดสอบ

7. ตัวเลือก: เพิ่ม Webhooks

หาก server ของคุณรับ signed HTTPS callbacks ได้ ให้สร้าง webhook endpoint:

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

บันทึก signing_secret แบบแสดงครั้งเดียวจาก response และตรวจทุก delivery ก่อนเชื่อถือ payload

8. ตัวเลือก: ส่ง Chat Turn

สำหรับโมเดล chat ให้เรียก Chat API แทน POST /api/v1/generations:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-chat-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

ใช้ session_id ที่ได้กลับมาเพื่อสนทนาต่อใน session ที่สร้างผ่าน API ไฟล์แนบรูปภาพต้องอ้างอิงค่า file_id จาก Files API

ตัวเลือก: ใช้ TypeScript SDK Beta

server-side TypeScript integrations สามารถใช้ local SDK beta:

import { RivyaClient } from "@rivya/sdk";

const rivya = new RivyaClient({
  apiKey: process.env.RIVYA_API_KEY
});

const generation = await rivya.generations.create({
  model: "z-image",
  prompt: "A clean editorial product image on a soft studio background"
});

อ่าน Rivya TypeScript SDK ก่อนนำไปใช้ SDK มี server-side Chat streaming support ใน private beta

เริ่มต้นใช้ Rivya API อย่างรวดเร็ว