สร้าง workflow หลายโมดัลด้วย Rivya API

การเชื่อมต่อ Rivya API ที่ดีไม่ใช่แค่ยิง request เดียวไปยังโมเดลเดียว

workflow ผลิตภัณฑ์จริงส่วนใหญ่มี chain สั้น ๆ: เลือกโมเดลที่ถูกต้อง เตรียม input อัปโหลด reference files เมื่อจำเป็น ส่ง job ติดตาม status จัดการ credits และแจ้งผลิตภัณฑ์เมื่อผลลัพธ์พร้อม

บทความนี้แสดงรูปแบบการวางแผน ใช้ Rivya API Quickstart สำหรับเส้นทางที่รันได้สั้นที่สุด และใช้เอกสาร API สำหรับ request fields ที่ถูกต้อง

เริ่มจาก product moment

ก่อนเลือก endpoints ให้อธิบาย product moment ในหนึ่งประโยค

ตัวอย่าง:

• Create a product image draft when a seller submits a listing brief.
• Generate a short video concept after a campaign manager approves a still direction.
• Send a chat turn inside an internal research tool and stream the response back to the user.
• Upload a reference image, submit a supported model request, and notify the user when the result is ready.

ประโยคนี้ช่วยกันไม่ให้ integration กลายเป็นชุด API calls ที่หลวม ๆ

map workflow ก่อนเขียน code

ใช้ตารางนี้ก่อนเปิด request schema

workflow ควรชัดพอที่ API area แต่ละส่วนมีเหตุผลในการมีอยู่

ขั้นที่ 1: สร้าง key สำหรับ integration

สร้าง API key สำหรับ app, environment หรือ workflow เฉพาะที่จะใช้มัน

หลีกเลี่ยงการใช้ key เดียวกับทุกอย่าง การตั้งชื่อ key ตาม purpose ทำให้รีวิวภายหลังง่ายขึ้น:

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

อ่าน API Authentication ก่อนจัดเก็บ key secret แบบเต็มจะแสดงเพียงครั้งเดียว ดังนั้นทีมควรบันทึกลงใน server-side secret store ที่ถูกต้องทันที

ขั้นที่ 2: เลือกโมเดลจาก public API list

อย่า hard-code โมเดลเพียงเพราะมันเคยใช้ได้ในการทดสอบ manual

ใช้ API Models และ Model API Reference เพื่อยืนยัน:

• ID โมเดลสาธารณะ
• เปิดให้ใช้ผ่าน API หรือไม่
• โหมดอินพุตที่รองรับ
• ความคาดหวังของ prompt และ parameter
• ต้องใช้ Files API หรือไม่
• credit behavior และ readiness notes

นี่คือจุดที่ integration จำนวนมากจะสะอาดขึ้น โมเดลที่เหมาะกับ manual Studio test อาจไม่ใช่โมเดลแรกที่ถูกต้องสำหรับ automated product flow

ขั้นที่ 3: ตัดสินว่า Files API อยู่ในเวอร์ชันแรกหรือไม่

ถ้าโมเดลรันจาก text input ได้ ให้เวอร์ชันแรกเป็น text-only

เพิ่ม Files API เฉพาะเมื่อ workflow ต้องใช้ reference media จริง ๆ

เมื่อจำเป็น ให้กำหนด:

• ผลิตภัณฑ์รับ file kinds ใด
• ใครเป็นเจ้าของขั้นตอน file cleanup
• จะเกิดอะไรขึ้นเมื่อ upload ล้มเหลว
• file data ที่ได้กลับมาจะถูกส่งเข้า model parameters อย่างไร
• file เดิมควรถูก reuse หรือ upload ใหม่

วิธีนี้ป้องกันไม่ให้ประสบการณ์ไฟล์ที่เปราะถูกซ่อนไว้หลังปุ่ม generate ที่ดูเรียบร้อย

ขั้นที่ 4: ส่ง generation job หนึ่งรายการ

สำหรับ image, video และ audio generation รูปแบบปกติคือ:

1. เตรียม model ID, prompt และ supported params
2. เพิ่ม idempotency key เพื่อ retry ได้ปลอดภัย
3. ส่งผ่าน generation endpoint
4. บันทึก public task ID
5. poll status จน task เข้าสู่ terminal state

ใช้ Create Generation สำหรับ request shape และ Generation Status สำหรับการจัดการผลลัพธ์

ผลิตภัณฑ์ควรมอง queued, processing, succeeded และ failed เป็น user-facing states อย่าให้ผู้ใช้ต้องอ่าน system details หรือเดาว่าทำไม job ช้า

ขั้นที่ 5: ใช้ Chat API สำหรับ chat models

chat models ควรใช้ Chat API ไม่ใช่ generation endpoint

เรื่องนี้สำคัญเพราะงาน chat มีพฤติกรรมต่างกัน:

• chat turns อาจอยู่ใน sessions ที่สร้างผ่าน API
• non-streaming และ SSE streaming ให้ประสบการณ์ผู้ใช้ต่างกัน
• image attachments ใช้ file IDs จาก Files API
• credit settlement ตาม chat turn แทนที่จะเป็น async media task ปกติ

ถ้าผลิตภัณฑ์ของคุณต้องการ assistant answer ใน interface ของตัวเอง Chat API อาจเป็นเส้นทางที่ถูกต้อง ถ้าผู้ใช้ยังสำรวจไอเดียอยู่ Rivya Chat หรือ Studio อาจดีกว่า

ขั้นที่ 6: เริ่มจาก polling แล้วค่อยเพิ่ม webhooks

สำหรับเวอร์ชันแรก polling เข้าใจง่ายกว่า

เพิ่ม API Webhooks เมื่อ:

• ผลิตภัณฑ์มี async jobs จำนวนมาก
• clients ที่รออยู่ไม่ควร poll โดยตรง
• downstream systems ต้องการ signed completion events
• retry และ duplicate handling ถูกออกแบบไว้แล้ว

webhook receivers ควรเรียบง่ายและเข้มงวด: verify signature, รับ events แบบ duplicate-safe, update product record เดียว และ log เฉพาะสิ่งที่ปลอดภัย

ขั้นที่ 7: ทำให้ credits มองเห็นได้ในผลิตภัณฑ์

Rivya API ใช้ account credits เดียวกับ Studio

integration ของคุณควรตัดสินว่าจะแสดงข้อมูลมากน้อยแค่ไหน อย่างน้อยทีมควรรู้:

• บัญชีใดเป็นเจ้าของ API key
• workflow ใดใช้ credits ได้
• จะเกิดอะไรขึ้นเมื่อ credits ต่ำเกินไป
• อธิบาย failed generation states อย่างไร
• ควรส่งใครไปที่ไหนสำหรับคำถามเรื่อง credit และ billing

ใช้ API Credits, Credits & Billing in Rivya และ How to Think About Rivya Credits, Packs, and Plans สำหรับ wallet model ที่ผู้ใช้เข้าใจได้

เวอร์ชันแรกขนาดเล็ก

เวอร์ชันแรกที่ดีควรจำกัดขอบเขตอย่างตั้งใจ

ตัวอย่าง:

1. API key หนึ่งอัน
2. โมเดล image ที่เลือกแล้วหนึ่งตัว
3. ยังไม่มี file upload
4. generation request หนึ่งรายการ
5. status polling path หนึ่งเส้น
6. result preview ง่าย ๆ หนึ่งจุดในผลิตภัณฑ์ของคุณ
7. credit error message ที่ชัดเจนหนึ่งข้อความ

เวอร์ชันนี้พิสูจน์การเชื่อมต่อก่อนเพิ่มส่วนเคลื่อนไหวอื่น

เวอร์ชันที่สมบูรณ์ขึ้น

หลังเวอร์ชันแรกทำงานแล้ว workflow ที่ครบขึ้นอาจเพิ่ม:

• Files API สำหรับ reference images หรือ videos
• การควบคุมพารามิเตอร์เฉพาะโมเดล
• idempotency ที่ผูกกับ product record ของคุณ
• signed webhooks สำหรับ completion
• Chat API สำหรับ assistant turns
• server-side event stream เมื่อ chat ต้องการ live output
• admin หรือ support views สำหรับ failed jobs

แต่ละส่วนเพิ่มควรตอบ product need จริง ถ้าแค่ทำให้ demo ดูใหญ่ขึ้น ให้ปล่อยไว้ก่อน

ข้อผิดพลาด integration ที่พบบ่อย

หลีกเลี่ยง patterns เหล่านี้:

• เริ่มด้วย API feature ทุกอย่างพร้อมกัน
• ซ่อน credit usage จาก account owner
• ใช้สมมติฐานแบบ Studio-only ใน API flow
• มอง file uploads เป็นรายละเอียดทีหลัง
• retry generation requests โดยไม่มี idempotency
• ใช้ Chat API กับ jobs ที่ควรเป็น async generation
• ใช้ generation endpoints กับ chat turns
• log API keys เต็ม, webhook secrets หรือ temporary file details

workflow API ที่ปลอดภัยที่สุดจะชัดเจนเรื่อง ownership, state และ failure handling

ไปต่อที่ไหน

• เริ่มจาก Developers สำหรับ public API hub
• ใช้ Rivya API Quickstart เพื่อรัน request แรก
• ใช้ API Models ก่อนเลือก model IDs
• ใช้ Files API เฉพาะเมื่อโมเดลต้องการ reference media จริง ๆ
• ใช้ Chat API สำหรับ chat turns และ streaming chat responses
• ใช้ API Webhooks เมื่อ polling ไม่พอแล้ว
• ถ้า workflow ยังต้องการการสำรวจโดยมนุษย์ อ่าน When to Use Rivya API Instead of Studio ก่อนทำ automation