Rivya API là gì?

Rivya API là đường dành cho developer để dùng năng lực mô hình Rivya từ sản phẩm, script hoặc workflow của riêng bạn.

Nó không phải một sản phẩm tách khỏi Rivya Studio. Nó dùng cùng ranh giới tài khoản, cùng ví credits và cùng lớp mô hình công khai mà người dùng thấy trên Rivya. Khác biệt nằm ở cách công việc bắt đầu: thay vì bấm qua Studio, ứng dụng của bạn gửi request bằng API key.

Nếu bạn cần chi tiết endpoint, hãy bắt đầu với Tổng quan Rivya API và Bắt đầu nhanh với Rivya API. Bài viết này là phần giải thích ở cấp sản phẩm: API dùng để làm gì, nằm ở đâu và khi nào không nên là đường đầu tiên.

Phiên bản ngắn

Rivya API v1 cho phép một tài khoản đã đăng nhập tạo API keys và gọi năng lực mô hình Rivya từ bên ngoài giao diện web.

Bề mặt API hiện tại gồm:

• khám phá mô hình qua danh sách mô hình API
• job tạo image, video và audio bất đồng bộ
• tải lên qua Files API cho các mô hình cần media tham chiếu
• polling trạng thái tạo sinh bằng public task IDs
• kiểm tra credits tài khoản
• lượt Chat API, bao gồm SSE streaming tùy chọn
• webhooks có chữ ký cho hoàn tất tạo sinh
• TypeScript SDK beta cho đội muốn có client wrapper

Hub developer công khai là Developers. Đây là điểm vào tốt nhất nếu bạn muốn tổng quan có hướng dẫn, liên kết tới cài đặt API key và một luồng debugger an toàn.

Vì sao Rivya có API

Studio hữu ích khi một người vẫn đang chọn mô hình, định hình prompt, rà soát đầu ra và quyết định làm gì tiếp theo.

API hữu ích khi quyết định đó đã biến thành một quy trình sản phẩm hoặc vận hành có thể lặp lại.

Ví dụ thường gặp:

• một sản phẩm muốn tạo biến thể hình ảnh sau khi người dùng gửi brief
• một workflow marketing cần tạo bản nháp hình ảnh từ đầu vào chiến dịch có cấu trúc
• một công cụ nội bộ cần gửi job video hoặc audio mà không yêu cầu ai mở trình duyệt
• một hệ thống support hoặc nội dung muốn có một lượt mô hình chat trong giao diện riêng
• một dịch vụ backend muốn callback có chữ ký khi job tạo sinh hoàn tất

Trong các trường hợp đó, Rivya API giữ công việc gắn với cùng tài khoản Rivya thay vì buộc bạn dựng một stack riêng cho billing, lựa chọn mô hình và trạng thái nhiệm vụ.

API không thay thế điều gì

API không thay thế mọi lý do để dùng Rivya trực tiếp.

Dùng Hướng dẫn Rivya Studio hoặc các bề mặt công việc công khai khi:

• prompt vẫn cần con người khám phá
• lựa chọn mô hình chưa ổn định
• creator cần so sánh đầu ra bằng mắt
• dự án phụ thuộc vào lịch sử đã lưu và rà soát thủ công
• đội chưa quyết định định dạng đầu vào và đầu ra nào nên trở thành phần lặp lại được

Dùng API khi workflow đã đủ rõ để tự động hóa.

Ranh giới đó quan trọng. Một câu hỏi sáng tạo mơ hồ thường thuộc về Studio trước. Một luồng sản phẩm đã biết với đầu vào dự đoán được có thể chuyển sang API.

Các khối xây dựng chính

Hãy xem API như sáu phần được kết nối.

Tài liệu API là nguồn chuẩn cho dạng request và response. Bài viết này chỉ giúp bạn quyết định phần nào cần dùng trước.

Credits hoạt động thế nào

Việc dùng API rút từ cùng ví credits tài khoản Rivya như Studio.

Điều đó nghĩa là API không phải proxy mô hình ẩn danh. Một request thuộc về một tài khoản Rivya, dùng API key do tài khoản đó tạo và tuân theo cùng ranh giới credits cấp sản phẩm được mô tả trong API Credits.

Điều này hữu ích cho đội vì thử nghiệm trong Studio và sử dụng API vẫn nằm trong một mô hình vận hành. Bạn có thể kiểm thử mô hình thủ công, rồi chuyển phần lặp lại được vào integration mà không tạo thêm lớp billing thứ hai.

Files nằm ở đâu

Một số mô hình có thể chạy chỉ từ văn bản. Một số khác cần ảnh, video hoặc audio tham chiếu.

Với integration API, các tham chiếu đó nên đi qua Files API. Việc tải lên tạo một bản ghi file được quản lý, có thể truyền vào các tham số mô hình được hỗ trợ.

Quy tắc thực tế rất đơn giản:

• nếu mô hình nhận đầu vào chỉ văn bản, hãy bắt đầu với generation endpoint
• nếu mô hình cần media tham chiếu, hãy tải file lên trước
• nếu mô hình chat cần ảnh đính kèm, hãy dùng Chat API và file IDs

Đừng thiết kế integration quanh luồng tải lên chỉ có trong trình duyệt hoặc session Studio đã lưu. API có ranh giới file công khai riêng vì một lý do rõ ràng.

Webhooks giúp ở đâu

Polling là đường integration đầu tiên dễ nhất. Gửi một generation job, lưu public task ID và poll cho đến khi thành công hoặc thất bại.

Webhooks trở nên hữu ích khi integration giống production hơn:

• bạn không muốn một worker poll mọi job
• ứng dụng cần cập nhật bản ghi khi tạo sinh hoàn tất
• bạn muốn một sự kiện có chữ ký và có thể retry an toàn
• job thất bại cần đi vào một đường phục hồi rõ ràng

Với hợp đồng sự kiện có chữ ký, hãy dùng API Webhooks. Giữ webhook receiver hẹp: xác minh chữ ký, xử lý sự kiện trùng lặp và tránh đưa giá trị bí mật vào logs.

Một dự án API đầu tiên tốt

Dự án API đầu tiên tốt nhất thường nhỏ và cụ thể.

Ví dụ:

1. tạo API key trong settings
2. gọi danh sách mô hình
3. chọn một mô hình khả dụng
4. gửi một generation job với idempotency key
5. poll status endpoint
6. kiểm tra credits trước và sau
7. chỉ sau đó mới thêm Files API, Chat API hoặc Webhooks

Đường đi đó cho bạn một integration hoạt động mà không trộn mọi tính năng API vào lần kiểm thử đầu tiên.

Khi API là điểm bắt đầu sai

API có lẽ không phải bước đầu đúng khi:

• đội chưa chọn họ mô hình
• đầu ra mong muốn vẫn thay đổi ở mỗi lượt chạy
• prompt phụ thuộc vào gu và rà soát thủ công
• integration sẽ che khuất việc dùng credits khỏi những người cần hiểu nó
• sản phẩm cần demo công khai trước khi cần tự động hóa

Trong các trường hợp đó, hãy bắt đầu từ Image, Video, Audio, Chat hoặc AI Models. Khi đường đi đã lặp lại được, hãy chuyển phần ổn định sang API.

Nên đi tiếp đến đâu

• Mở Developers để xem hub API công khai và debugger.
• Đọc Bắt đầu nhanh với Rivya API để tạo request an toàn đầu tiên.
• Đọc Xác thực API trước khi đặt key lên server.
• Đọc API Models trước khi chọn model IDs.
• Đọc Khi nào nên dùng Rivya API thay vì Studio nếu ranh giới sản phẩm vẫn chưa rõ.
• Đọc Cách xây quy trình AI đa phương thức với Rivya API khi bạn đang lập kế hoạch integration đầy đủ cho image, video, audio hoặc chat.