สร้างเวิร์กโฟลว์หลายรูปแบบด้วย Rivya API

การเชื่อมต่อ Rivya API ที่ดีไม่ได้มีเพียงการส่งคำขอเดียวไปยังโมเดลเดียว

เวิร์กโฟลว์ของผลิตภัณฑ์จริงมักมีขั้นตอนต่อเนื่องสั้น ๆ ได้แก่ เลือกโมเดล เตรียมข้อมูลนำเข้า อัปโหลดไฟล์อ้างอิงเมื่อจำเป็น ส่งงาน ติดตามสถานะ จัดการเครดิต และแจ้งผลิตภัณฑ์เมื่อผลลัพธ์พร้อม

บทความนี้อธิบายวิธีวางแผน ใช้ คู่มือเริ่มต้น Rivya API สำหรับเส้นทางที่สั้นที่สุดซึ่งรันได้จริง และดูเอกสาร API เมื่อต้องการชื่อฟิลด์คำขอที่ถูกต้อง

เวิร์กโฟลว์ด้านล่างอ้างอิงสัญญา Public API ที่ระบบรองรับแล้ว ก่อนเริ่มพัฒนา ให้ยืนยันว่าระบบที่นำไปใช้และบัญชีเปิดใช้ Public API โมเดลที่เลือกพร้อมให้เรียกผ่าน API และฟีเจอร์เสริมอย่างเว็บฮุกเปิดใช้งานจริง

เริ่มจากช่วงเวลาสำคัญในผลิตภัณฑ์

ก่อนเลือกจุดเชื่อมต่อ ให้อธิบายช่วงเวลาที่ผลิตภัณฑ์ต้องทำงานในหนึ่งประโยค

ตัวอย่าง:

• 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.

ประโยคนี้ช่วยไม่ให้การเชื่อมต่อกลายเป็นเพียงชุดการเรียก API ที่ไม่สัมพันธ์กัน

วางผังเวิร์กโฟลว์ก่อนเขียนโค้ด

ใช้ตารางนี้ก่อนเปิดดูโครงสร้างคำขอ

เวิร์กโฟลว์ควรชัดเจนพอที่จะอธิบายได้ว่าแต่ละส่วนของ API มีไว้เพื่ออะไร

ขั้นที่ 1: สร้างคีย์สำหรับการเชื่อมต่อ

สร้างคีย์ API สำหรับแอป สภาพแวดล้อม หรือเวิร์กโฟลว์ที่จะใช้คีย์นั้นโดยเฉพาะ

หลีกเลี่ยงการใช้คีย์เดียวกับทุกอย่าง การตั้งชื่อคีย์ตามจุดประสงค์ช่วยให้ตรวจสอบภายหลังได้ง่ายขึ้น:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

อ่าน การยืนยันตัวตนของ API ก่อนจัดเก็บคีย์ ค่าลับแบบเต็มจะแสดงเพียงครั้งเดียว ทีมจึงควรบันทึกลงในระบบจัดเก็บข้อมูลลับฝั่งเซิร์ฟเวอร์ที่เหมาะสมทันที

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

อย่ากำหนดโมเดลตายตัวเพียงเพราะโมเดลนั้นเคยใช้ได้ในการทดสอบด้วยตนเอง

ใช้ API โมเดล และ โมเดล API ข้อมูลอ้างอิง เพื่อยืนยัน:

• ID โมเดลสาธารณะ

• เปิดให้ใช้ผ่าน API หรือไม่

• โหมดอินพุตที่รองรับ

• ข้อกำหนดของพรอมต์และพารามิเตอร์

• ต้องใช้ ไฟล์ API หรือไม่

• พฤติกรรมการใช้เครดิตและข้อมูลความพร้อมใช้งาน

นี่คือจุดที่การเชื่อมต่อจำนวนมากจะเป็นระเบียบขึ้น โมเดลที่เหมาะกับการทดสอบด้วยตนเองใน Studio อาจไม่ใช่โมเดลแรกที่เหมาะกับกระบวนการผลิตภัณฑ์แบบอัตโนมัติ

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

ถ้าโมเดลทำงานจากข้อความได้ ให้เวอร์ชันแรกใช้เฉพาะข้อความ

เพิ่ม Files API เฉพาะเมื่อเวิร์กโฟลว์ต้องใช้สื่ออ้างอิงจริง ๆ

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

• ผลิตภัณฑ์รับไฟล์ประเภทใด

• ใครรับผิดชอบขั้นตอนล้างไฟล์

• จะเกิดอะไรขึ้นเมื่ออัปโหลดล้มเหลว

• ข้อมูลไฟล์ที่ได้กลับมาจะถูกส่งเข้าไปในพารามิเตอร์ของโมเดลอย่างไร

• ควรนำไฟล์เดิมกลับมาใช้หรืออัปโหลดใหม่

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

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

สำหรับการสร้างภาพ วิดีโอ และเสียง รูปแบบทั่วไปคือ:

1. เตรียมรหัสโมเดล พรอมต์ และพารามิเตอร์ที่รองรับ

2. เพิ่มคีย์ป้องกันคำขอซ้ำเพื่อให้ลองใหม่ได้อย่างปลอดภัย

3. ส่งคำขอผ่านจุดเชื่อมต่อสำหรับงานสร้าง

4. บันทึกรหัสงานสาธารณะ

5. ตรวจสถานะซ้ำจนงานเข้าสู่สถานะสิ้นสุด

ใช้ สร้างงาน เพื่อดูโครงสร้างคำขอ และ สถานะงานสร้าง เพื่อจัดการผลลัพธ์

ผลิตภัณฑ์ควรมอง queued, processing, succeeded และ failed เป็น ที่ผู้ใช้มองเห็น สถานะ อย่าให้ผู้ใช้ต้องอ่าน ระบบ รายละเอียด หรือเดาว่าทำไม งาน ช้า

ขั้นที่ 5: ใช้ การสนทนา API สำหรับ การสนทนา โมเดล

การสนทนา โมเดล ควรใช้ การสนทนา API ไม่ใช่ การสร้าง จุดเชื่อมต่อ

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

• การสนทนา รอบสนทนา อาจอยู่ใน เซสชัน ที่สร้างผ่าน API

• แบบไม่สตรีม และ SSE การสตรีม ให้ประสบการณ์ผู้ใช้ต่างกัน

• ไฟล์แนบรูปภาพใช้รหัสไฟล์จาก Files API

• การหักเครดิตคิดตามรอบสนทนา ไม่ใช่ตามงานสร้างสื่อแบบอะซิงโครนัสทั่วไป

หากผลิตภัณฑ์ต้องแสดงคำตอบจากผู้ช่วยในส่วนติดต่อของตัวเอง Chat API อาจเป็นเส้นทางที่เหมาะสม แต่หากผู้ใช้ยังสำรวจแนวคิดอยู่ Rivya Chat หรือ Studio อาจเหมาะกว่า

ขั้นที่ 6: เริ่มจาก การตรวจสถานะซ้ำ แล้วค่อยเพิ่ม เว็บฮุก

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

หาก ระบบที่นำไปใช้งาน เปิดใช้ เว็บฮุก แล้ว ให้เพิ่ม API เว็บฮุก เมื่อ:

• ผลิตภัณฑ์มี แบบไม่รอผล งาน จำนวนมาก

• ลูกค้า ที่รออยู่ไม่ควร ตรวจสถานะซ้ำ โดยตรง

• ระบบขั้นถัดไปต้องได้รับเหตุการณ์แจ้งว่างานเสร็จสมบูรณ์และมีลายเซ็นกำกับ

• ออกแบบการลองใหม่และการจัดการเหตุการณ์ซ้ำไว้แล้ว

ตัวรับเว็บฮุกควรเรียบง่ายและเข้มงวด: ตรวจสอบลายเซ็น รองรับเหตุการณ์ซ้ำอย่างปลอดภัย อัปเดตข้อมูลผลิตภัณฑ์เพียงระเบียนเดียว และบันทึกเฉพาะข้อมูลที่ปลอดภัย

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

Rivya API ใช้ บัญชี เครดิต เดียวกับ Studio

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

• บัญชีใดเป็นเจ้าของ API คีย์

• ขั้นตอนการทำงาน ใดใช้ เครดิต ได้

• จะเกิดอะไรขึ้นเมื่อ เครดิต ต่ำเกินไป

• อธิบาย ล้มเหลว การสร้าง สถานะ อย่างไร

• ควรส่งใครไปที่ไหนสำหรับคำถามเรื่อง เครดิต และ การเรียกเก็บเงิน

ใช้ เครดิต API, เครดิตและการเรียกเก็บเงินใน Rivya และ วิธีคิดเกี่ยวกับเครดิต แพ็ก และแผนของ Rivya เพื่ออธิบายรูปแบบกระเป๋าเครดิตให้ผู้ใช้เข้าใจ

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

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

ตัวอย่าง:

1. API คีย์ หนึ่งอัน

2. โมเดล ภาพ ที่เลือกแล้วหนึ่งตัว

3. ยังไม่มี ไฟล์ อัปโหลด

4. การสร้าง คำขอ หนึ่งรายการ

5. สถานะ การตรวจสถานะซ้ำ เส้นทาง หนึ่งเส้น

6. จุดแสดงตัวอย่างผลลัพธ์แบบเรียบง่ายหนึ่งจุดในผลิตภัณฑ์

7. เครดิต ข้อผิดพลาด ข้อความ ที่ชัดเจนหนึ่งข้อความ

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

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

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

• ไฟล์ API สำหรับ ภาพอ้างอิง หรือ วิดีโอ

• การควบคุมพารามิเตอร์เฉพาะโมเดล

• คีย์ป้องกันคำขอซ้ำที่ผูกกับระเบียนผลิตภัณฑ์ของคุณ

• ที่ลงชื่อเข้าใช้ เว็บฮุก สำหรับแจ้ง การทำงานเสร็จ เมื่อฟีเจอร์นี้เปิดใช้งาน

• Chat API สำหรับรอบสนทนากับผู้ช่วย

• เหตุการณ์สตรีมจากเซิร์ฟเวอร์เมื่อแชตต้องส่งผลลัพธ์แบบทันที

• มุมมองสำหรับผู้ดูแลหรือทีมซัพพอร์ตเพื่อตรวจงานที่ล้มเหลว

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

ข้อผิดพลาด การเชื่อมต่อ ที่พบบ่อย

หลีกเลี่ยง รูปแบบ เหล่านี้:

• เริ่มด้วย API ฟีเจอร์ ทุกอย่างพร้อมกัน

• ซ่อนการใช้เครดิตจากเจ้าของบัญชี

• ใช้สมมติฐานแบบ Studio-เท่านั้น ใน API ขั้นตอน

• มอง ไฟล์ ไฟล์อัปโหลด เป็นรายละเอียดทีหลัง

• ลองส่งคำขอสร้างใหม่โดยไม่มีคีย์ป้องกันคำขอซ้ำ

• ใช้ การสนทนา API กับ งาน ที่ควรเป็น แบบไม่รอผล การสร้าง

• ใช้จุดเชื่อมต่องานสร้างกับรอบสนทนาอย่างสับสน

• บันทึกคีย์ API แบบเต็ม ค่าลับของเว็บฮุก หรือรายละเอียดไฟล์ชั่วคราวลงในระบบ

ขั้นตอนการทำงาน API ที่ปลอดภัยที่สุดจะชัดเจนเรื่อง ความเป็นเจ้าของ, สถานะ และ ความล้มเหลว การจัดการ

ไปต่อที่ไหน

• เริ่มจาก นักพัฒนา ซึ่งเป็นศูนย์รวม API สาธารณะ

• ใช้ คู่มือเริ่มต้นใช้งาน Rivya API เพื่อส่งคำขอแรก

• ใช้ โมเดล API ก่อนเลือกรหัสโมเดล

• ใช้ ไฟล์ API เฉพาะเมื่อโมเดลต้องการ ข้อมูลอ้างอิง สื่อ จริง ๆ

• ใช้ การสนทนา API สำหรับ การสนทนา รอบสนทนา และ การสตรีม การสนทนา คำตอบ

• ใช้ API เว็บฮุก เมื่อ การตรวจสถานะซ้ำ ไม่พอและเปิดสิทธิ์ใช้ เว็บฮุก แล้ว

• หากเวิร์กโฟลว์ยังต้องการการสำรวจโดยมนุษย์ อ่าน ควรใช้ Rivya API หรือ Studio เมื่อใด ก่อนทำระบบอัตโนมัติ