Μια καλή ενσωμάτωση Rivya API δεν είναι απλώς ένα αίτημα προς ένα μοντέλο.

Οι περισσότερες πραγματικές ροές προϊόντος έχουν μια μικρή αλυσίδα: επιλέξτε το σωστό μοντέλο, ετοιμάστε την είσοδο, ανεβάστε αρχεία αναφοράς όταν χρειάζεται, υποβάλετε μια εργασία, παρακολουθήστε την κατάσταση, χειριστείτε τα credits και ειδοποιήστε το προϊόν όταν το αποτέλεσμα είναι έτοιμο.

Αυτό το άρθρο δείχνει το σχήμα σχεδιασμού. Χρησιμοποιήστε το Γρήγορη εκκίνηση του Rivya API για τη συντομότερη εκτελέσιμη διαδρομή και τα έγγραφα API για τα ακριβή πεδία αιτήματος.

Ξεκινήστε από τη στιγμή προϊόντος

Πριν επιλέξετε τελικά σημεία, περιγράψτε τη στιγμή προϊόντος σε μία πρόταση.

Παραδείγματα:

Δημιούργησε πρόχειρη εικόνα προϊόντος όταν ένας πωλητής υποβάλλει σύνοψη καταχώρισης.
Δημιούργησε σύντομη ιδέα βίντεο αφού ένας διαχειριστής καμπάνιας εγκρίνει μια στατική κατεύθυνση.
Στείλε έναν γύρο chat μέσα σε εσωτερικό εργαλείο έρευνας και κάνε streaming την απάντηση πίσω στον χρήστη.
Ανέβασε μια εικόνα αναφοράς, υπέβαλε αίτημα υποστηριζόμενου μοντέλου και ειδοποίησε τον χρήστη όταν το αποτέλεσμα είναι έτοιμο.

Αυτή η πρόταση αποτρέπει την ενσωμάτωση από το να γίνει χαλαρή συλλογή κλήσεων API.

Χαρτογραφήστε τη ροή εργασίας πριν γράψετε κώδικα

Χρησιμοποιήστε αυτόν τον πίνακα πριν ανοίξετε το schema αιτήματος.

Βήμα ροής εργασίας	Ερώτηση προϊόντος	Περιοχή API
Πρόσβαση λογαριασμού	Ποιος λογαριασμός Rivya κατέχει τη χρήση;	Πιστοποίηση API
Επιλογή μοντέλου	Ποιο δημόσιο model ID ταιριάζει σε αυτή την εργασία;	Μοντέλα API
Είσοδος αναφοράς	Χρειάζεται το μοντέλο ανεβασμένα media;	Files API
Δημιουργία	Είναι αυτή ασύγχρονη εργασία εικόνας, βίντεο ή ήχου;	Δημιουργία generation
Chat	Είναι αυτό γύρος μοντέλου chat αντί για εργασία δημιουργίας;	Chat API
Κατάσταση	Πώς θα ξέρει το προϊόν ότι το αποτέλεσμα είναι έτοιμο;	Κατάσταση generation
Συμβάν ολοκλήρωσης	Πρέπει άλλο σύστημα να λάβει υπογεγραμμένο callback;	API Webhooks
Credits	Πώς θα κατανοήσει η ομάδα το κόστος;	API Credits

Η ροή εργασίας πρέπει να είναι αρκετά σαφής ώστε κάθε περιοχή API να έχει λόγο ύπαρξης.

Βήμα 1: Δημιουργήστε κλειδί για την ενσωμάτωση

Δημιουργήστε ένα API key για τη συγκεκριμένη εφαρμογή, περιβάλλον ή ροή εργασίας που θα το χρησιμοποιήσει.

Αποφύγετε να χρησιμοποιείτε ένα κλειδί για όλα. Η ονομασία κλειδιών με βάση τον σκοπό κάνει τον μεταγενέστερο έλεγχο ευκολότερο:

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

Διαβάστε το Πιστοποίηση API πριν αποθηκεύσετε το κλειδί. Το πλήρες μυστικό εμφανίζεται μία φορά, οπότε η ομάδα σας πρέπει να το αποθηκεύσει αμέσως στη σωστή αποθήκη μυστικών στην πλευρά του διακομιστή.

Βήμα 2: Επιλέξτε μοντέλα από τη δημόσια λίστα API

Μην κωδικοποιείτε σταθερά ένα μοντέλο μόνο επειδή λειτούργησε σε χειροκίνητη δοκιμή.

Χρησιμοποιήστε τα Μοντέλα API και Αναφορά API μοντέλων για να επιβεβαιώσετε:

το δημόσιο model ID
αν είναι διαθέσιμο μέσω API
την υποστηριζόμενη λειτουργία εισόδου
τις προσδοκίες prompt και παραμέτρων
αν απαιτείται Files API
συμπεριφορά credits και σημειώσεις ετοιμότητας

Εδώ πολλές ενσωματώσεις καθαρίζουν. Ένα μοντέλο που είναι τέλειο για χειροκίνητη δοκιμή Studio μπορεί να μην είναι το σωστό πρώτο μοντέλο για αυτοματοποιημένη ροή προϊόντος.

Βήμα 3: Αποφασίστε αν το Files API ανήκει στην πρώτη έκδοση

Αν το μοντέλο μπορεί να τρέξει από είσοδο κειμένου, κρατήστε την πρώτη έκδοση μόνο με κείμενο.

Προσθέστε Files API μόνο όταν η ροή εργασίας χρειάζεται πραγματικά media αναφοράς.

Όταν το κάνει, ορίστε:

ποια είδη αρχείων δέχεται το προϊόν
ποιος κατέχει το βήμα καθαρισμού αρχείων
τι συμβαίνει όταν αποτύχει η μεταφόρτωση
πώς τα επιστρεφόμενα δεδομένα αρχείου περνούν στις παραμέτρους μοντέλου
αν το ίδιο αρχείο πρέπει να επαναχρησιμοποιηθεί ή να ανεβεί ξανά

Αυτό αποτρέπει μια εύθραυστη εμπειρία αρχείων από το να κρυφτεί πίσω από ένα κουμπί δημιουργίας που μοιάζει καθαρό.

Βήμα 4: Υποβάλετε μία εργασία δημιουργίας

Για δημιουργία εικόνας, βίντεο και ήχου, το κανονικό μοτίβο είναι:

ετοιμάστε το model ID, το prompt και τις υποστηριζόμενες παραμέτρους
προσθέστε idempotency key για ασφαλείς επαναλήψεις
υποβάλετε μέσω του endpoint δημιουργίας
αποθηκεύστε το δημόσιο task ID
κάντε polling κατάστασης μέχρι η εργασία να φτάσει σε τελική κατάσταση

Χρησιμοποιήστε το Δημιουργία generation για το σχήμα αιτήματος και το Κατάσταση generation για τον χειρισμό αποτελεσμάτων.

Το προϊόν πρέπει να αντιμετωπίζει τα queued, processing, succeeded και failed ως καταστάσεις που βλέπει ο χρήστης. Μην κάνετε τους χρήστες να διαβάζουν λεπτομέρειες συστήματος ή να μαντεύουν γιατί μια εργασία είναι αργή.

Βήμα 5: Χρησιμοποιήστε Chat API για μοντέλα chat

Τα μοντέλα chat πρέπει να χρησιμοποιούν Chat API, όχι το endpoint δημιουργίας.

Αυτό έχει σημασία επειδή η δουλειά chat έχει διαφορετική συμπεριφορά:

οι γύροι chat μπορούν να ανήκουν σε sessions που δημιουργήθηκαν από API
το non-streaming και το SSE streaming έχουν διαφορετικές εμπειρίες χρήστη
τα συνημμένα εικόνων χρησιμοποιούν file IDs από Files API
ο διακανονισμός credits ακολουθεί τον γύρο chat αντί για κανονική ασύγχρονη εργασία media

Αν το προϊόν σας χρειάζεται απάντηση assistant μέσα στη δική του διεπαφή, το Chat API μπορεί να είναι η σωστή διαδρομή. Αν ο χρήστης ακόμη εξερευνά ιδέες, το Rivya Chat ή το Studio μπορεί να είναι καλύτερο.

Βήμα 6: Ξεκινήστε με polling και μετά προσθέστε webhooks

Για πρώτη έκδοση, το polling είναι ευκολότερο να το σκεφτείτε.

Προσθέστε API Webhooks όταν:

το προϊόν έχει πολλές ασύγχρονες εργασίες
οι πελάτες που περιμένουν δεν πρέπει να κάνουν απευθείας polling
μεταγενέστερα συστήματα χρειάζονται υπογεγραμμένα συμβάντα ολοκλήρωσης
ο χειρισμός επανάληψης και διπλότυπων έχει ήδη σχεδιαστεί

Οι δέκτες webhook πρέπει να είναι βαρετοί και αυστηροί: επαληθεύστε την υπογραφή, αποδεχτείτε συμβάντα ασφαλή ως προς τα διπλότυπα, ενημερώστε μία εγγραφή προϊόντος και καταγράψτε μόνο ό,τι είναι ασφαλές να καταγραφεί.

Βήμα 7: Κάντε τα credits ορατά στο προϊόν

Το Rivya API χρησιμοποιεί τα ίδια credits λογαριασμού με το Studio.

Η ενσωμάτωσή σας πρέπει να αποφασίσει πόσα από αυτά θα δείχνει. Τουλάχιστον, η ομάδα πρέπει να ξέρει:

ποιος λογαριασμός κατέχει το API key
ποια ροή εργασίας μπορεί να καταναλώνει credits
τι συμβαίνει όταν τα credits είναι πολύ χαμηλά
πώς εξηγούνται οι αποτυχημένες καταστάσεις δημιουργίας
πού να στείλει κάποιον για ερωτήσεις credits και χρέωσης

Χρησιμοποιήστε τα API Credits, Credits και χρέωση στο Rivya και Πώς να σκέφτεστε τα Rivya Credits, Packs και Plans για το μοντέλο πορτοφολιού που βλέπει ο χρήστης.

Μια μικρή πρώτη έκδοση

Μια καλή πρώτη έκδοση είναι σκόπιμα περιορισμένη.

Για παράδειγμα:

ένα API key
ένα επιλεγμένο μοντέλο εικόνας
χωρίς μεταφόρτωση αρχείου ακόμη
ένα αίτημα δημιουργίας
μία διαδρομή polling κατάστασης
μία απλή προεπισκόπηση αποτελέσματος στο προϊόν σας
ένα σαφές μήνυμα σφάλματος credits

Αυτή η έκδοση αποδεικνύει τη σύνδεση πριν προσθέσετε περισσότερα κινούμενα μέρη.

Μια πιο πλήρης έκδοση

Αφού λειτουργήσει η πρώτη έκδοση, μια πληρέστερη ροή εργασίας μπορεί να προσθέσει:

Files API για εικόνες ή βίντεο αναφοράς
ελέγχους παραμέτρων ειδικούς για μοντέλο
idempotency δεμένη με την εγγραφή προϊόντος σας
υπογεγραμμένα webhooks για ολοκλήρωση
Chat API για γύρους assistant
ροή συμβάντων από τον διακομιστή όπου το chat χρειάζεται ζωντανή έξοδο
προβολές διαχείρισης ή υποστήριξης για αποτυχημένες εργασίες

Κάθε προσθήκη πρέπει να απαντά σε πραγματική ανάγκη προϊόντος. Αν απλώς κάνει την επίδειξη να φαίνεται μεγαλύτερη, αφήστε την έξω.

Συνηθισμένα λάθη ενσωμάτωσης

Αποφύγετε αυτά τα μοτίβα:

να ξεκινάτε με κάθε δυνατότητα API ταυτόχρονα
να κρύβετε τη χρήση credits από τον κάτοχο λογαριασμού
να χρησιμοποιείτε υποθέσεις μόνο του Studio σε ροή API
να αντιμετωπίζετε τις μεταφορτώσεις αρχείων ως δευτερεύουσα σκέψη
να επαναλαμβάνετε αιτήματα δημιουργίας χωρίς idempotency
να χρησιμοποιείτε Chat API για εργασίες που πρέπει να είναι ασύγχρονη δημιουργία
να χρησιμοποιείτε τελικά σημεία δημιουργίας για γύρους chat
να καταγράφετε πλήρη API keys, webhook secrets ή προσωρινές λεπτομέρειες αρχείων

Η ασφαλέστερη ροή εργασίας API είναι ρητή για την ιδιοκτησία, την κατάσταση και τον χειρισμό αποτυχίας.

Πού να πάτε μετά

Ξεκινήστε από Developers για τον δημόσιο κόμβο API.
Χρησιμοποιήστε το Γρήγορη εκκίνηση του Rivya API για να εκτελέσετε το πρώτο αίτημα.
Χρησιμοποιήστε τα Μοντέλα API πριν επιλέξετε model IDs.
Χρησιμοποιήστε Files API μόνο όταν το μοντέλο χρειάζεται πραγματικά media αναφοράς.
Χρησιμοποιήστε Chat API για γύρους chat και streaming απαντήσεις chat.
Χρησιμοποιήστε API Webhooks όταν το polling δεν αρκεί πια.
Αν η ροή εργασίας χρειάζεται ακόμη ανθρώπινη εξερεύνηση, διαβάστε Πότε να χρησιμοποιείτε Rivya API αντί για Studio πριν την αυτοματοποιήσετε.

Δημιουργήστε πολυτροπική ροή εργασίας με το Rivya API