Rivya Journal
Tác giả
Danh mục
Mục lục
Tiếp tục khám phá
Tiếp tục với hướng dẫn liên quan, ghi chú sản phẩm và phân tích quy trình từ đội ngũ Rivya.
Một tích hợp Rivya API tốt không chỉ là một yêu cầu tới một mô hình.
Hầu hết quy trình sản phẩm thật có một chuỗi nhỏ: chọn đúng mô hình, chuẩn bị đầu vào, tải tệp tham chiếu lên khi cần, gửi job, theo dõi trạng thái, xử lý điểm tín dụng và thông báo cho sản phẩm khi kết quả đã sẵn sàng.
Bài này cho thấy hình dạng lập kế hoạch. Dùng Bắt đầu nhanh với Rivya API cho lộ trình chạy được ngắn nhất, và dùng tài liệu API cho các trường yêu cầu chính xác.
Quy trình dưới đây mô tả hợp đồng Public API đã được triển khai. Trước khi xây dựng, hãy xác nhận Public API đã bật cho bản triển khai và tài khoản, mô hình được chọn sẵn sàng cho API, và tính năng tùy chọn như webhook thực sự khả dụng.
Trước khi chọn điểm cuối, hãy mô tả khoảnh khắc sản phẩm trong một câu.
Ví dụ:
Tạo bản nháp hình ảnh sản phẩm khi seller gửi listing brief.
Tạo concept video ngắn sau khi campaign manager duyệt hướng ảnh tĩnh.
Gửi một chat turn trong công cụ nghiên cứu nội bộ và stream phản hồi lại cho người dùng.
Tải ảnh tham chiếu lên, gửi request mô hình được hỗ trợ và thông báo cho người dùng khi kết quả sẵn sàng.
Câu đó ngăn tích hợp trở thành một tập hợp API call rời rạc.
Dùng bảng này trước khi mở yêu cầu lược đồ.
| Bước quy trình | Câu hỏi sản phẩm | Khu vực API |
|---|---|---|
| Truy cập tài khoản | Tài khoản Rivya nào sở hữu lượt sử dụng? | Xác thực API |
| Chọn mô hình | ID mô hình công khai nào phù hợp với công việc này? | Mô hình API |
| Đầu vào tham chiếu | Mô hình có cần media đã tải lên không? | Files API |
| Generation | Đây là job ảnh, video hay âm thanh async? | Tạo tạo nội dung |
| Chat | Đây là một trò chuyện mô hình turn thay vì tạo nội dung job? | Chat API |
| Status | Sản phẩm biết kết quả sẵn sàng bằng cách nào? | Trạng thái tạo nội dung |
| Sự kiện hoàn tất | Hệ thống khác có cần nhận callback đã ký và webhook đã được bật chưa? | API Webhooks |
| Điểm tín dụng | Đội ngũ hiểu chi phí bằng cách nào? | API Điểm tín dụng |
Quy trình nên đủ rõ để mỗi khu vực API đều có lý do tồn tại.
Tạo API key cho ứng dụng, môi trường hoặc quy trình cụ thể sẽ dùng nó.
Tránh dùng một key cho mọi thứ. Đặt tên key theo mục đích giúp rà soát sau này dễ hơn:
production-image-workflow
staging-video-tests
internal-chat-assistant
webhook-smoke-test
Đọc Xác thực API trước khi lưu key. Secret đầy đủ chỉ hiển thị một lần, vì vậy đội ngũ nên lưu ngay vào nơi lưu secret phía máy chủ phù hợp.
Đừng hard-mã một mô hình chỉ vì nó hoạt động trong một bài kiểm thử thủ công.
Dùng Mô hình API và Tham chiếu API mô hình để xác nhận:
công khai mô hình ID
nó có sẵn qua API không
chế độ đầu vào được hỗ trợ
kỳ vọng về câu lệnh và tham số
Files API có bắt buộc không
hành vi điểm tín dụng và ghi chú readiness
Đây là nơi nhiều tích hợp trở nên sạch hơn. Một mô hình hoàn hảo cho bài kiểm thử thủ công trong Studio chưa chắc là mô hình đầu tiên đúng cho luồng sản phẩm tự động.
Nếu mô hình có thể chạy từ đầu vào văn bản, hãy giữ phiên bản đầu chỉ dùng text.
Chỉ thêm Files API khi quy trình thật sự cần media tham chiếu.
Khi cần, hãy xác định:
sản phẩm chấp nhận loại tệp nào
ai sở hữu bước làm sạch tệp
điều gì xảy ra khi tải lên thất bại
dữ liệu tệp trả về được truyền vào tham số mô hình như thế nào
cùng một tệp nên được tái sử dụng hay tải lại
Điều này ngăn một trải nghiệm tệp mong manh bị giấu sau một nút generate trông sạch sẽ.
Với tạo ảnh, video và âm thanh, mẫu thông thường là:
chuẩn bị mô hình ID, câu lệnh và params được hỗ trợ
thêm idempotency key để thử lại an toàn
gửi qua tạo nội dung điểm cuối
lưu công khai tác vụ ID
thăm dò trạng thái cho đến khi tác vụ đạt trạng thái kết thúc
Dùng Tạo tạo nội dung cho hình dạng yêu cầu và Trạng thái tạo nội dung cho xử lý kết quả.
Sản phẩm nên xem queued, processing, succeeded và failed là các trạng thái hướng người dùng. Đừng bắt người dùng đọc chi tiết hệ thống hoặc đoán vì sao job chậm.
Các mô hình trò chuyện nên dùng Chat API, không phải tạo nội dung điểm cuối.
Điều đó quan trọng vì trò chuyện work có hành vi khác:
trò chuyện turns có thể thuộc về phiêns được tạo bởi API
non-truyền theo luồng và SSE truyền theo luồng có trải nghiệm người dùng khác nhau
hình ảnh attachments dùng tệp IDs từ Files API
quyết toán điểm tín dụng đi theo trò chuyện turn thay vì media tác vụ async thông thường
Nếu sản phẩm của bạn cần câu trả lời assistant bên trong giao diện riêng, Chat API có thể là lộ trình đúng. Nếu người dùng vẫn đang khám phá ý tưởng, Rivya Chat hoặc Studio có thể tốt hơn.
Với phiên bản đầu, polling dễ suy luận hơn.
Nếu webhook đã bật cho bản triển khai, hãy thêm API Webhooks khi:
sản phẩm có nhiều async jobs
ứng dụng khách đang chờ không nên thăm dò trực tiếp
hệ thống downstream cần signed completion events
thử lại và xử lý duplicate đã được thiết kế
Bộ nhận webhook nên nhàm chán và nghiêm ngặt: xác minh signature, chấp nhận sự kiện an toàn khi lặp, cập nhật một bản ghi sản phẩm và chỉ log những gì an toàn để log.
Rivya API dùng cùng tài khoản điểm tín dụng như Studio.
Tích hợp của bạn nên quyết định hiển thị bao nhiêu phần. Tối thiểu, đội ngũ nên biết:
tài khoản nào sở hữu API key
quy trình nào có thể tiêu thụ điểm tín dụng
điều gì xảy ra khi điểm tín dụng quá thấp
trạng thái tạo nội dung thất bại được giải thích thế nào
gửi ai đến đâu cho câu hỏi về điểm tín dụng và thanh toán
Dùng API Điểm tín dụng, Điểm tín dụng & Billing trong Rivya, và Cách hiểu điểm tín dụng, packs và kế hoạch của Rivya cho mô hình ví người dùng nhìn thấy.
Một phiên bản đầu tốt nên được giới hạn có chủ ý.
Ví dụ:
một API key
một mô hình hình ảnh đã chọn
chưa tải lên tệp
một tạo nội dung yêu cầu
một đường thăm dò trạng thái
một preview kết quả đơn giản trong sản phẩm của bạn
một thông báo lỗi điểm tín dụng rõ ràng
Phiên bản này chứng minh kết nối trước khi thêm nhiều phần chuyển động hơn.
Sau khi phiên bản đầu hoạt động, một quy trình đầy đủ hơn có thể thêm:
Files API cho ảnh hoặc video tham chiếu
kiểm soát tham số theo mô hình
idempotency gắn với product record của bạn
webhook đã ký cho sự kiện hoàn tất khi tính năng này được bật
Chat API cho assistant turns
máy chủ-side sự kiện luồng khi trò chuyện cần đầu ra trực tiếp
view admin hoặc hỗ trợ cho jobs thất bại
Mỗi phần thêm vào nên trả lời một nhu cầu sản phẩm thật. Nếu nó chỉ làm demo trông lớn hơn, hãy bỏ ra.
Tránh các mẫu này:
bắt đầu bằng mọi tính năng API cùng lúc
giấu usage điểm tín dụng khỏi chủ tài khoản
dùng giả định chỉ đúng trong Studio cho API flow
xem tệp tệp tải lên như chi tiết phụ
thử lại tạo nội dung requests mà không có idempotency
dùng Chat API cho jobs đáng ra phải là async tạo nội dung
dùng tạo nội dung endpoints cho trò chuyện turns
log API keys đầy đủ, webhook secrets hoặc chi tiết tệp tạm
Quy trình API an toàn nhất nói rõ ownership, state và failure handling.
Bắt đầu từ Developers cho công khai API hub.
Dùng Bắt đầu nhanh với Rivya API để chạy yêu cầu đầu tiên.
Dùng Mô hình API trước khi chọn mô hình IDs.
Chỉ dùng Files API khi mô hình thật sự cần media tham chiếu.
Dùng Chat API cho trò chuyện turns và truyền theo luồng trò chuyện responses.
Dùng API Webhooks khi polling không còn đủ và quyền truy cập webhook đã được bật.
Nếu quy trình vẫn cần khám phá thủ công, hãy đọc Khi nào nên dùng Rivya API thay vì Studio trước khi tự động hóa.
