สร้างคีย์ API เลือกโมเดล ส่งงานสร้างแบบอะซิงโครนัส และส่งข้อความหนึ่งรอบผ่าน Chat API พร้อมเลือกสตรีมด้วย SSE ได้

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

ใช้คีย์ตัวอย่างในเอกสารและโค้ดเสมอ ห้ามวางคีย์ API จริงในโค้ดสาธารณะ ภาพหน้าจอ ตั๋วขอความช่วยเหลือ หรือเอกสารที่แชร์กับผู้อื่น

ตัวอย่างต่อไปนี้อ้างอิงสัญญา Public API v1 ที่ระบบรองรับ ก่อนทดสอบ โปรดยืนยันว่าระบบที่ให้บริการจริงเปิดการเข้าถึง Public API และบัญชีของคุณได้รับสิทธิ์แล้ว การมีเอกสารของจุดเชื่อมต่อหรือหน้าโมเดลไม่ได้ยืนยันว่าคำขอจะทำงานได้ในทุกสภาพแวดล้อม

1. สร้างคีย์ API

เปิด การตั้งค่าคีย์ API สร้างคีย์ คัดลอกค่าลับฉบับเต็มในครั้งที่ระบบแสดง แล้วเก็บไว้ในตัวแปรสภาพแวดล้อมฝั่งเซิร์ฟเวอร์

ขอบเขตสิทธิ์ชุดแรกที่แนะนำ:

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

2. ยืนยัน URL หลัก

ใช้ URL หลักของ API สำหรับระบบจริง:

https://rivya.ai

URL บนเครื่องใช้สำหรับการพัฒนาในเครื่องเท่านั้น ตัวอย่างที่เผยแพร่สู่สาธารณะไม่ควรใช้ค่าลับจากเครื่องของคุณ

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

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

เมื่อต้องสร้างงาน ให้นำค่าในช่อง id จากผลตอบกลับไปใช้เป็นค่า model

4. ส่งงานสร้าง

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

ผลตอบกลับจะมีรหัสงานสาธารณะ โปรดบันทึกรหัสนี้ไว้เพื่อตรวจสถานะภายหลัง

5. ตรวจสถานะเป็นระยะ

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

สถานะที่เป็นไปได้มีดังนี้:

queued
processing
succeeded
failed

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

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

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

7. ตัวเลือกเสริม: เพิ่มเว็บฮุก

หากระบบที่ให้บริการจริงและบัญชีของคุณได้รับสิทธิ์ใช้เว็บฮุก และเซิร์ฟเวอร์ของคุณรับจุดเรียกกลับแบบ HTTPS ที่มีลายเซ็นได้ ให้สร้างจุดเชื่อมต่อเว็บฮุกดังนี้:

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 ซึ่งแสดงเพียงครั้งเดียวจากผลตอบกลับ และตรวจสอบการส่งข้อมูลทุกครั้งก่อนเชื่อถือเนื้อหาที่ได้รับ

8. ตัวเลือกเสริม: ส่งข้อความสนทนาหนึ่งรอบ

สำหรับโมเดลสนทนา ให้เรียก 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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

ใช้ session_id ที่ได้รับเพื่อสนทนาต่อในเซสชันซึ่งสร้างผ่าน API ส่วนภาพแนบต้องอ้างอิงค่า file_id จาก Files API

ตัวเลือกเสริม: ใช้ชุดพัฒนา TypeScript รุ่นเบตา

การเชื่อมต่อ TypeScript ฝั่งเซิร์ฟเวอร์สามารถใช้ชุดพัฒนารุ่นเบตาที่อยู่ในโครงการได้:

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

อ่าน ชุดพัฒนา TypeScript ของ Rivya ก่อนนำไปใช้ ชุดพัฒนานี้รองรับการสตรีมการสนทนาฝั่งเซิร์ฟเวอร์ในรุ่นเบตาส่วนตัว

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