HappyOysterEngine configure l'hôte et le modèle Open Platform, met à jour le jeton de clé API temporaire Model Studio et crée des sessions Travel. Travel est l'objet de session retourné par createTravel() ; la session est rejointe et démarrée uniquement après l'appel de travel.start(). Prend en charge les modes aventure, réalisation et jeu d'acteur.
HappyOysterEngine configure l'hôte Open Platform, met à jour le jeton de clé API temporaire Model Studio et crée des sessions Travel.
Travel est l'objet de session retourné par createTravel(). La session est rejointe et démarrée uniquement après l'appel de travel.start().
Terminologie de base
Terme | Signification | Remarques |
|---|---|---|
token | Jeton de clé API temporaire Model Studio : lors de l'appel aux services Model Studio depuis des environnements non approuvés tels que des navigateurs ou des applications mobiles, générez une clé API temporaire via un backend sécurisé pour éviter d'exposer une clé API permanente. Le SDK envoie ce jeton à Open Platform en tant qu'identifiant HTTP Bearer. | |
ticket | Identifiant de session Travel du monde HappyOyster : votre backend appelle l'API d'identification en utilisant l'authentification AK (en-tête de passerelle) pour obtenir un identifiant de session Travel à courte durée de vie ( |
Vue d'ensemble
Le SDK fournit les objets principaux suivants :
HappyOysterEngine
API | Description |
|---|---|
| Crée une instance Engine. |
| Met à jour le token de clé API temporaire Model Studio utilisé par les requêtes API Open Platform suivantes. |
| Crée une session Travel. |
| La version actuelle du SDK. |
| Le nom du package SDK actuel, sa version et son canal de distribution. |
Voyage
API | Description |
|---|---|
| Démarre la session Travel actuelle. |
| S'abonne aux changements de statut de session. |
| S'abonne aux notifications d'URL de première image. |
| S'abonne aux métadonnées de session disponibles immédiatement après l'entrée dans le travel. |
| S'abonne aux erreurs d'exécution de session. |
| Vérifie si l'action spécifiée peut actuellement être appelée. |
| Obtient les métadonnées de session disponibles ; retourne |
| Envoie une commande de contrôle en temps réel. |
| Envoie des instructions Directing ou du contenu de prompt. |
| Met en pause la session actuelle. |
| Reprend une session en pause. |
| Rembobine une session Directing au moment spécifié. |
| Termine la session actuelle et libère ses ressources. |
Autres exports
Export | Description |
|---|---|
| L'objet constant de codes d'erreur exporté par le SDK. |
| Vérifie si une erreur inconnue est une erreur standard du SDK. |
Types | Types publics tels que |
Exemple
HappyOysterEngine
HappyOysterEngine est le point d'entrée du SDK Web. Il configure l'hôte Open Platform, gère le jeton de clé API temporaire Model Studio utilisé par les requêtes suivantes et crée des sessions Travel.
Travel actif à la fois. Terminez le Travel actuel avant de démarrer une nouvelle session.Une fois qu'un jeton est défini soit dans le constructeur, soit via updateToken(), le SDK récupère en interne la configuration Feature Gate. Cela permet à la plateforme de désactiver le SDK à distance ou d'exiger que les anciennes versions effectuent une mise à niveau. Si la requête échoue, le SDK adopte un comportement permissif et ne bloque pas l'expérience normale.API | Description |
|---|---|
| Crée une instance Engine avec l'hôte API et le modèle requis, ainsi qu'un jeton et un niveau de journalisation facultatifs. |
| Met à jour le token de clé API temporaire Model Studio utilisé par les requêtes Open Platform suivantes. |
| Crée une session Travel qui n'a pas encore démarré. |
new HappyOysterEngine
Crée une instance HappyOysterEngine.
Signature
Paramètres
SDKConfig
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Hôte API Open Platform. Il doit s'agir d'un hôte nu, tel que |
|
| Oui | Identifiant du modèle Open Platform à utiliser. Obligatoire, sans valeur par défaut. Fixe pour ce Engine et partagé par tous ses Travels. |
|
| Non | Jeton de clé API temporaire Model Studio défini lors de la construction. Il peut également être défini ultérieurement avec |
|
| Non | Niveau de journalisation du SDK. La valeur par défaut est |
|
| Non | Délai d'attente pour que |
model sur un identifiant de modèle, tel que happyoyster-1.0-adventure, un modèle Adventure. Utilisez l'identifiant de modèle correspondant à votre environnement de service cible. Le SDK ne choisit pas un modèle à partir du mode d'expérience et ne le déduit pas du ticket.
Un Engine a une combinaison APIHost + model fixe. Réutilisez-le pour des Travels successifs ciblant le même service et le même modèle. Avant de changer l'une ou l'autre valeur, terminez le Travel actif et utilisez un Engine configuré pour la nouvelle cible. Créez le monde et émettez son ticket par rapport à la même cible de service.
Retourne
Retourne une instance HappyOysterEngine.
Erreurs
Si config est manquant, ou si APIHost, model, token, logLevel ou streamReadyTimeout a un type ou une valeur invalide, une SdkError avec le code ErrorCode.INVALID_ARGUMENT (10010001) est levée de manière synchrone. Passer une URL complète, une chaîne vide ou une valeur avec un chemin comme APIHost est invalide.
model est obligatoire et doit être une chaîne non vide après suppression des espaces ; null, les valeurs non chaînes et les chaînes contenant uniquement des espaces sont invalides. L'omettre ou passer undefined déclenche également une erreur d'argument ; le SDK n'a pas de modèle par défaut.
HappyOysterEngine.updateToken
Met à jour le token de clé API temporaire Model Studio utilisé par les requêtes API Open Platform suivantes.
Signature
Paramètres
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Token de clé API temporaire Model Studio. Passer une chaîne vide efface le token actuel. |
Retourne
Ne retourne rien.
Erreurs
Si token n'est pas une chaîne, une SdkError avec le code ErrorCode.INVALID_ARGUMENT (10010001) est levée de manière synchrone.
HappyOysterEngine.createTravel
Crée une instance de session Travel sans la démarrer.
Signature
Paramètres
CreateTravelConfig
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Ticket utilisé pour démarrer le Travel ultérieurement. |
|
| Oui | L'élément |
|
| Non | Durée maximale de l'expérience Aventure, en secondes. Les sessions Réalisation et Jeu d'acteur ignorent ce champ. En cas d'omission, le serveur applique sa valeur par défaut. |
Retourne
Retourne une session Travel créée mais pas encore démarrée. L'appelant doit ensuite exécuter await travel.start() pour entrer dans la session et attendre que la vidéo devienne lisible.
Chaque instance HappyOysterEngine ne peut avoir qu'un seul Travel actif à la fois. Appelez await travel.end() avant de créer un autre Travel.
Erreurs
createTravel() déclenche une SdkError de manière synchrone dans les cas suivants :
ErrorCode | Description |
|---|---|
|
|
| Un Travel est déjà actif ; appelez d'abord |
travel.start().
Travel
Travel représente une session créée par HappyOysterEngine.createTravel(). Elle est initialement inactive. Après l'appel de travel.start(), le SDK entre dans la session et attend que la vidéo devienne lisible.
Travel prend en charge le démarrage, la mise en pause, la reprise, le rembobinage et la fin d'une session ; l'envoi de contrôles et d'invites en temps réel ; ainsi que l'abonnement aux changements d'état et aux erreurs d'exécution.
Méthodes
Méthode | Description |
|---|---|
| Démarre la session Travel actuelle. |
| S'abonne aux changements de statut de session. |
| S'abonne aux notifications d'URL de première image. |
| S'abonne aux métadonnées de session disponibles immédiatement après l'entrée dans le travel. |
| S'abonne aux erreurs d'exécution de session. |
| Vérifie si l'action spécifiée peut actuellement être appelée. |
| Obtient les métadonnées de session disponibles ; retourne |
| Envoie une commande de contrôle en temps réel. |
| Envoie des instructions Directing ou du contenu de prompt. |
| Met en pause la session actuelle. |
| Reprend une session en pause. |
| Rembobine la session actuelle au moment spécifié. |
| Termine la session actuelle et libère ses ressources. |
Statut
Statut | Description |
|---|---|
| La session n'a pas démarré. |
| La session démarre et attend que la vidéo devienne lisible. |
| La session est en cours d'exécution. |
| La session est en pause et peut être reprise ou rembobinée. |
| La session s'est terminée normalement et ses ressources ont été libérées. |
Événements
Abonnez-vous aux événements avec travel.on(event, handler). La méthode retourne une fonction de désabonnement.
Événement | Callback | Description |
|---|---|---|
|
| Le statut de la session a changé. |
|
| Émis pendant |
|
| Émis après le retour de enter-travel et avant la connexion RTC. |
|
| Une erreur d'exécution de session. |
Travel.can
Vérifie si une action est disponible pour le statut actuel et la capacité de la session.
Signature
Paramètres
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Action à vérifier : |
Retourne
Retourne une boolean. true signifie que l'action est actuellement disponible ; false signifie que l'état, le mode ou la capacité de session actuel ne répond pas à ses préconditions.
Disponibilité
action | Disponibilité |
|---|---|
| Travel est toujours |
|
|
|
|
|
|
|
|
|
|
| Le Travel n'a pas été fermé. |
Erreurs
Cette méthode ne déclenche pas d'erreurs métier. Les actions inconnues retournent false.
Travel.start
Démarre la session Travel actuelle.
Signature
Paramètres
Aucun paramètre.
Retourne
Retourne une Promise<StartTravelResult>, qui se résout après le démarrage de la session et lorsque la vidéo devient lisible.
Après le retour de enter-travel, le SDK émet travelInfoReady avant de connecter le RTC. Les abonnés tardifs peuvent appeler travel.getInfo() ; cela retourne null avant que les métadonnées ne soient disponibles. Si la réponse inclut une firstFrame non vide, firstFrameGenerated suit tout de même.
StartTravelResult
Champ | Type | Description |
|---|---|---|
|
| ID de la session Travel actuelle. |
|
| Mode de session : |
|
| Modèle de création de monde ; les valeurs courantes sont |
|
| URL de l'image de la première image ; |
|
| Durée maximale de l'expérience Aventure, en secondes. |
|
| Format d'image Acting ; |
Erreurs
start() est rejeté et émet un événement error dans les cas suivants. Utilisez isSdkError(err) pour vérifier l'erreur et lire err.code et err.message.
ErrorCode | Description |
|---|---|
| La fonctionnalité SDK est désactivée ( |
| Impossible de démarrer : l'état actuel ne le permet pas, Open Platform n'est pas configuré ou l'entrée dans la session a échoué |
| Impossible de démarrer : la configuration de session retournée par le serveur est incomplète |
| Impossible de démarrer : échec de la connexion au flux vidéo ou échec de la requête de flag de fonctionnalité SDK |
| Impossible de démarrer : délai d'attente dépassé pour le flux vidéo (utilise la plus grande valeur entre |
| Impossible de démarrer : délai d'attente dépassé pour que la vidéo devienne lisible (contrôlé par |
| Erreur de paramètre, de ressource ou de serveur Open Platform |
Travel.on("statusChanged")
S'abonne aux changements de statut de session.
Signature
Paramètres
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Callback invoqué lorsque le statut change. |
Retourne
Retourne une fonction de désabonnement. TravelStatus est l'une des valeurs suivantes : idle / prepare / running / paused / completed.
Erreurs
Cette méthode ne déclenche pas d'erreurs métier.
Travel.on("firstFrameGenerated")
S'abonne aux notifications d'URL de première image.
Signature
Paramètres
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Callback invoqué lorsque l'URL de la première image est disponible. |
Retourne
Retourne une fonction de désabonnement.
Comportement
Émis uniquement pendant travel.start(). Après que le SDK a appelé enter-travel d'Open Platform et reçu une firstFrame non vide, il émet l'événement immédiatement — généralement après statusChanged("prepare") mais avant que start() ne se résolve et que la vidéo ne devienne lisible. L'événement n'est pas émis si la réponse ne contient aucune URL de première image.
Erreurs
Cette méthode ne déclenche pas d'erreurs métier.
Travel.onError
S'abonne aux erreurs d'exécution de session.
Signature
Paramètres
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Callback invoqué lorsqu'une erreur d'exécution se produit. |
Retourne
Retourne une fonction de désabonnement. Utilisez isSdkError pour restreindre l'objet d'erreur à SdkError.
Erreurs
Cette méthode ne déclenche pas d'erreurs métier.
Travel.sendCommand
Envoie une commande de contrôle en temps réel.
Signature
Paramètres
AdventureCommand
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Non | Direction du mouvement. La valeur par défaut est |
|
| Non | Rotation de la vue. La valeur par défaut est |
|
| Non | Action d'interaction. La valeur par défaut est |
Référence des commandes de contrôle
translation — Direction du mouvement
Décrit le mouvement du personnage, prenant en charge huit directions et leurs combinaisons.
Valeur | Direction |
|---|---|
| Avant |
| Arrière |
| Gauche |
| Droite |
| Avant-gauche |
| Avant-droite |
| Arrière-gauche |
| Arrière-droite |
| Immobile |
rotation — Rotation de la vue
Simule une rotation de vue basée sur la souris dans huit directions.
Valeur | Direction |
|---|---|
| Haut |
| Bas |
| Gauche |
| Droite |
| Haut-gauche |
| Haut-droite |
| Bas-gauche |
| Bas-droite |
| None |
interaction — Action d'interaction
Valeur | Action |
|---|---|
| Saut |
| Attaque |
| Accroupi |
| Sprint |
| None |
Retourne
Retourne un Promise<void> qui se résout après la soumission de la commande.
Erreurs
sendCommand() est rejeté dans les cas suivants :
ErrorCode | Description |
|---|---|
|
|
| Le statut actuel ou le mode de session n'autorise pas les commandes, ou la commande de flux vidéo a échoué |
Travel.sendInstruct
Envoie des instructions Directing ou du contenu de prompt.
Signature
Paramètres
InstructData
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Contenu du prompt à envoyer. |
Retourne
Retourne une Promise<void> qui se résout après que Open Platform a reçu et traité l'instruction.
Erreurs
sendInstruct() est rejeté et émet un événement error dans les cas suivants :
ErrorCode | Description |
|---|---|
| La session n'a pas démarré |
| Échec de l'envoi de l'instruction Directing |
| Erreur de paramètre, de ressource ou de serveur Open Platform |
Travel.pause
Met en pause la session actuelle.
Signature
Paramètres
Aucun paramètre.
Retourne
Retourne un Promise<void> qui se résout après l'arrêt de la lecture vidéo.
Erreurs
pause() est rejeté dans les cas suivants :
ErrorCode | Description |
|---|---|
| L'état actuel, le mode de session ou la capacité de session ne permet pas la mise en pause, ou la demande de mise en pause a échoué |
| Délai d'attente dépassé pour que le backend signale le flux vidéo comme étant en pause (15 secondes) |
| Erreur de paramètre, de ressource ou de serveur Open Platform |
Travel.resume
Reprend une session en pause.
Signature
Paramètres
Aucun paramètre.
Retourne
Retourne un Promise<void> qui se résout après que la vidéo redevient lisible.
Erreurs
resume() est rejeté dans les cas suivants :
ErrorCode | Description |
|---|---|
| L'état actuel, le mode de session ou la capacité de session ne permet pas la reprise, ou la demande de reprise a échoué |
| Délai d'attente dépassé pour que la vidéo redevienne lisible (15 secondes) |
| Erreur de paramètre, de ressource ou de serveur Open Platform |
Travel.rewind
Rembobine la session actuelle au moment spécifié.
Signature
Paramètres
RewindTravelParams
Champ | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Temps cible en secondes. Seuls les multiples de 4 sont pris en charge (par exemple, |
Retourne
Retourne une Promise<RewindTravelResult> qui se résout une fois le rembobinage terminé et la lecture reprise.
RewindTravelResult
Champ | Type | Description |
|---|---|---|
|
| Le temps réel en secondes auquel le serveur a repris la lecture. |
Erreurs
rewind() est rejeté et émet un événement error dans les cas suivants :
ErrorCode | Description |
|---|---|
| La session n'a pas démarré |
| Impossible de rembobiner : la session doit d'abord être mise en pause et la lecture vidéo arrêtée, ou la demande de rembobinage ou la reconnexion RTC a échoué |
| Délai d'attente dépassé pour la reprise de la vidéo après rembobinage (15 secondes) |
| Erreur de paramètre, de ressource ou de serveur Open Platform |
Travel.end
Termine la session actuelle et libère ses ressources.
Signature
Paramètres
Aucun paramètre.
Retourne
Retourne un Promise<void> qui se résout après la fin du nettoyage.
Erreurs
Les erreurs de nettoyage ne sont pas déclenchées vers l'appelant ; end() fait de son mieux pour libérer les ressources.
Gestion des erreurs
Le SDK expose les erreurs d'exécution via des rejets de Promise ou des événements error. Les erreurs sont des objets SdkError ; utilisez isSdkError(err) et lisez err.code et err.message.
Les erreurs Open Platform reconnues correspondent à la plage 10000001–10000012, et err.message contient le message de la plateforme. Consultez la section Erreurs de chaque API Travel pour les codes spécifiques aux méthodes.
Référence des ErrorCode
Plages de codes d'erreur :
100000xx: Erreurs Open Platform mappées1001xxxx: Erreurs client Engine1002xxxx: Erreurs client Travel
code | name | Description |
|---|---|---|
|
| Paramètres de requête invalides (retournés par Open Platform) |
|
| Ressource introuvable (Travel manquant, non possédé, dans un autre espace de travail ou artefact non prêt) |
|
| Le monde n'existe pas, a été supprimé ou n'appartient pas au développeur actuel |
|
| Erreur système |
|
| Le ticket est invalide ou expiré |
|
| Le ticket a déjà été utilisé (identifiant à usage unique) |
|
| Le monde n'est pas prêt et ne peut pas être rejoint |
|
| Échec de l'allocation des ressources d'inférence (capacité insuffisante, échec de création de flux, échec d'initialisation de session, etc.) |
|
| Cette API accepte uniquement la clé API principale (les clés API temporaires ne sont pas prises en charge) |
|
| Entrée rejetée par la modération de contenu |
|
| L'image d'entrée viole la politique de droit d'auteur ou de propriété intellectuelle |
|
| La requête est en conflit avec l'état actuel de la ressource |
|
| Échec de la validation des arguments du client SDK (non mappé depuis Open Platform) |
|
| La fonctionnalité SDK est désactivée |
|
| Un Travel est déjà actif |
|
| Flux vidéo déconnecté pendant la lecture |
|
| Échec de la demande de démarrage de session |
|
| Configuration du flux vidéo manquante lors du démarrage |
|
| Échec de la connexion au flux vidéo |
|
| Délai d'attente dépassé pour le flux vidéo |
|
| Délai d'attente dépassé pour que la vidéo devienne lisible |
|
| Échec de la demande de pause |
|
| Délai d'attente dépassé pour la mise en pause de la vidéo |
|
| Échec de la demande de reprise |
|
| Délai d'attente dépassé pour la reprise de la vidéo |
|
| Échec de la demande de rembobinage |
|
| Délai d'attente dépassé pour la reprise de la vidéo après rembobinage |
|
| Échec de l'envoi de la commande de contrôle en temps réel |
|
| Échec de l'envoi de l'instruction Directing |
|
| Échec de la demande de fin de session |
Autres exports
Exports d'exécution
Export | Type | Description |
|---|---|---|
|
| Client SDK qui configure Open Platform, met à jour le token et crée des sessions Travel. |
|
| La version actuelle du SDK. |
|
| Le nom du package SDK actuel, sa version et son canal de distribution. |
|
| L'objet constant de codes d'erreur exporté par le SDK. |
|
| Vérifie si une erreur inconnue est une erreur standard du SDK. |
ErrorCode
L'objet constant de codes d'erreur exporté par le SDK. Comparez-le avec SdkError.code au lieu de disperser des littéraux numériques dans le code de l'application.
isSdkError
Vérifie si une erreur inconnue est une erreur SDK standard. Lorsqu'elle retourne true, TypeScript réduit l'erreur à SdkError, permettant un accès sécurisé à code et message.
Types publics
Les types suivants sont exportés depuis le point d'entrée du package et peuvent être importés directement depuis @happy-oyster/js-sdk. Ils n'existent qu'au moment de la compilation TypeScript et ne produisent aucun code d'exécution.
Type | Description |
|---|---|
| Type de paramètre du constructeur |
| Niveaux de journalisation SDK : |
| Métadonnées du package SDK : |
| Canaux de package SDK : |
| Type de paramètre de |
| Métadonnées de session |
| Métadonnées de session utilisées par |
| Format d'image Acting : |
| Contrat de session public |
| États de session SDK locaux : |
| Noms d'action pris en charge par |
| Type de paramètre de |
| Type de paramètre de |
| Type de paramètre de |
| Données |
| Structure d'erreur SDK contenant |
| Type d'erreur combinant l' |
| Union de toutes les valeurs de codes d'erreur dans l'objet |