Một tích hợp Rivya API tốt không chỉ là một request tới một mô hình.

Hầu hết workflow 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ý credits 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 request chính xác.

Bắt đầu từ khoảnh khắc sản phẩm

Trước khi chọn endpoint, 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.

Vẽ workflow trước khi viết code

Dùng bảng này trước khi mở request schema.

Bước workflow	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	Public model ID nào phù hợp với công việc này?	API Models
Đầ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 generation
Chat	Đây là một chat model turn thay vì generation 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 generation
Completion event	Hệ thống khác có cần callback đã ký không?	API Webhooks
Credits	Đội ngũ hiểu chi phí bằng cách nào?	API Credits

Workflow nên đủ rõ để mỗi khu vực API đều có lý do tồn tại.

Bước 1: Tạo key cho tích hợp

Tạo API key cho ứng dụng, môi trường hoặc workflow 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 review 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 server phù hợp.

Bước 2: Chọn mô hình từ danh sách public API

Đừng hard-code một mô hình chỉ vì nó hoạt động trong một bài test thủ công.

Dùng API Models và Tham chiếu API mô hình để xác nhận:

public model ID
nó có sẵn qua API không
chế độ đầu vào được hỗ trợ
kỳ vọng về prompt và tham số
Files API có bắt buộc không
hành vi credits 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 test 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.

Bước 3: Quyết định Files API có thuộc phiên bản đầu khô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 workflow 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 cleanup tệp
điều gì xảy ra khi upload 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ẽ.

Bước 4: Gửi một generation job

Với tạo ảnh, video và âm thanh, mẫu thông thường là:

chuẩn bị model ID, prompt và params được hỗ trợ
thêm idempotency key để retry an toàn
gửi qua generation endpoint
lưu public task ID
poll status cho đến khi task đạt trạng thái kết thúc

Dùng Tạo generation cho hình dạng request và Trạng thái generation 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.

Bước 5: Dùng Chat API cho chat models

Các mô hình chat nên dùng Chat API, không phải generation endpoint.

Điều đó quan trọng vì chat work có hành vi khác:

chat turns có thể thuộc về sessions được tạo bởi API
non-streaming và SSE streaming có trải nghiệm người dùng khác nhau
image attachments dùng file IDs từ Files API
quyết toán credits đi theo chat turn thay vì media task 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.

Bước 6: Bắt đầu bằng polling, rồi thêm webhooks

Với phiên bản đầu, polling dễ suy luận hơn.

Thêm API Webhooks khi:

sản phẩm có nhiều async jobs
client đang chờ không nên poll trực tiếp
hệ thống downstream cần signed completion events
retry 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.

Bước 7: Làm credits rõ trong sản phẩm

Rivya API dùng cùng account credits 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
workflow nào có thể tiêu thụ credits
điều gì xảy ra khi credits quá thấp
trạng thái generation thất bại được giải thích thế nào
gửi ai đến đâu cho câu hỏi về credits và billing

Dùng API Credits, Credits & Billing trong Rivya, và Cách hiểu credits, packs và plans của Rivya cho mô hình ví người dùng nhìn thấy.

Một phiên bản đầu nhỏ

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 upload tệp
một generation request
một đường poll status
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 credits 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.

Một phiên bản hoàn chỉnh hơn

Sau khi phiên bản đầu hoạt động, một workflow đầ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
signed webhooks cho completion
Chat API cho assistant turns
server-side event stream khi chat cần đầu ra trực tiếp
view admin hoặc support 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.

Lỗi tích hợp thường gặp

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 credits khỏi chủ tài khoản
dùng giả định chỉ đúng trong Studio cho API flow
xem file uploads như chi tiết phụ
retry generation requests mà không có idempotency
dùng Chat API cho jobs đáng ra phải là async generation
dùng generation endpoints cho chat turns
log API keys đầy đủ, webhook secrets hoặc chi tiết tệp tạm

Workflow API an toàn nhất nói rõ ownership, state và failure handling.

Đi đâu tiếp theo

Bắt đầu từ Developers cho public API hub.
Dùng Bắt đầu nhanh với Rivya API để chạy request đầu tiên.
Dùng API Models trước khi chọn model IDs.
Chỉ dùng Files API khi mô hình thật sự cần media tham chiếu.
Dùng Chat API cho chat turns và streaming chat responses.
Dùng API Webhooks khi polling không còn đủ.
Nếu workflow 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.

Xây workflow đa phương thức với Rivya API