HappyOyster est un modèle de monde ouvert interactif en temps réel. À partir d'un simple prompt en langage naturel et d'une première image, il génère un monde numérique que vous pouvez interpréter, explorer et avec lequel vous pouvez interagir en temps réel, fourni sous forme de flux vidéo en direct rejoignable. Il est parfaitement adapté aux dramas interactifs, à la prévisualisation de films, aux compagnons IA et aux mondes jouables.
Pour les présentations de modèles et les conseils de rédaction de prompts, consultez le Guide HappyOyster.
HappyOyster propose trois modes d'expérience, chacun déployé indépendamment pour couvrir différents scénarios :
HappyOyster utilise un modèle d'intégration serveur + client :
Le module « Model Usage » dans la console ne prend pas encore en charge les statistiques d'utilisation du modèle de monde. Consultez plutôt votre utilisation via la page de facturation.
Introduction
HappyOyster propose trois modes d'expérience, chacun déployé indépendamment pour couvrir différents scénarios :
| Mode | Entrée | Interaction |
|---|---|---|
| Aventure | Prompt + première image (paysage) | Commandes directionnelles / de caméra / d'action (sendCommand) |
| Réalisation | Prompt ou script structuré + première image (paysage), images de référence facultatives (utilisées pour la génération de script et la référence de personnage) | Instructions textuelles (sendInstruct) / liste de scripts ; prend en charge la pause, le rembobinage et la reprise |
| Interprétation | Prompt + première image (portrait 9:16 par défaut, 16:9 également pris en charge) | Instructions textuelles (sendInstruct) ; prend en charge la pause et la reprise ; ne prend pas en charge le rembobinage |
Architecture
HappyOyster utilise un modèle d'intégration serveur + client :
- Votre serveur gère l'ensemble du cycle de vie du World via les Open API HappyOyster (avec la clé API principale, via HTTPS REST standard) : créer / gérer les worlds, échanger des identifiants, et interroger l'historique et les artefacts. Les Open API sont divisées par mode d'expérience en trois suites distinctes : Adventure, Directing et Acting.
- Votre client offre l'expérience en temps réel via le SDK HappyOyster (avec une clé API temporaire +
ticket, sur un canal audio/vidéo en temps réel RTC), prenant en charge Android, iOS et le Web. Le SDK encapsule la connexion RTC, la lecture vidéo, l'interrogation d'état et les commandes interactives, afin que vous n'ayez pas à travailler directement avec le protocole temps réel sous-jacent.
- Créez le World et obtenez les identifiants côté backend. Avec la clé API principale, votre backend envoie
POST /worldsà l'Open API HappyOyster pour créer le World, interroge l'état de sa construction avecGET /worlds/build-status, puis obtient les identifiants de l'expérience avecPOST /worlds/get-travel-credential. Le backend transmet letokenet leticketau client. - Démarrez l'expérience en temps réel côté client. Le client utilise le SDK, une clé API temporaire et le
ticket. Il appelleinitializeetupdateToken, puisstartTravel(ticket). Le SDK entre ensuite dans l'expérience via l'Open API, établit la connexion RTC et renvoie au client la View vidéo ainsi que les rappels d'état. - Interagissez depuis le client. Le client passe par le SDK pour appeler
sendInstruct,sendCommand,pauseouend. Le SDK appelle les API de contrôle correspondantes de l'Open API. - Récupérez les artefacts après la session. Votre backend envoie
GET /travels/artifactsà l'Open API pour récupérer les artefacts.
Open API et SDK
Responsabilités
| Dimension | Open API HappyOyster côté serveur | SDK HappyOyster côté client |
|---|---|---|
| Appelant | Votre backend | Votre application ou frontend web |
| Identifiants | Clé API principale (à long terme, conservée uniquement sur le serveur) | Clé API temporaire (token) + à usage unique ticket (à courte durée de vie) |
| Responsabilités principales | Gestion du monde (création, interrogation d'état, requête, suppression) ; échange d'identifiants ; contrôle du Travel ; requête d'artefacts | Connexion RTC et rendu vidéo ; commandes d'interaction en temps réel ; contrôle de session ; rappels d'état |
| Communication | HTTPS REST standard | Canal audio/vidéo en temps réel RTC (encapsulé dans le SDK) |
| Plateformes prises en charge | Tout langage backend (Python, Java, Node.js, etc.) | Android, iOS, Web |
Carte des capacités
| Capacité | Open API (serveur) | SDK (client) |
|---|---|---|
| Créer / gérer le monde | Pris en charge | Non pris en charge |
| Interroger l'état de construction du monde | Pris en charge | Non pris en charge |
Échanger ticket | Pris en charge | Non pris en charge (consomme ticket) |
| Injecter le token d'authentification HTTP | Non pris en charge | Pris en charge (updateToken) |
| Entrer dans la salle + connexion RTC | Pris en charge (invoqué en interne par le SDK) | Pris en charge (démarrage du Travel, encapsulé dans le SDK) |
| Lecture vidéo en temps réel | Non pris en charge | Pris en charge (attacher la vue vidéo fournie par le SDK ; pour Interprétation, utiliser le aspectRatio renvoyé pour définir l'orientation portrait / paysage) |
| Interrogation d'état | Pris en charge (invoqué en interne par le SDK) | Pris en charge (affiché via les rappels d'état) |
| Instructions textuelles pour Réalisation / Interprétation | Pris en charge (instruct) | Pris en charge (sendInstruct) |
| Commandes de contrôle Aventure | Non pris en charge | Pris en charge (sendCommand; non disponible en Interprétation) |
| Pause / reprise | Pris en charge | Pris en charge (Réalisation et Interprétation ; les appels Aventure sont rejetés par le SDK avec 103003) |
| Rembobinage | Pris en charge (rewind; Réalisation uniquement) | Pris en charge (Réalisation uniquement ; les autres modes sont rejetés avec 103003) |
| Terminer l'expérience | Pris en charge | Pris en charge (fin du Travel, encapsulé dans le SDK) |
| Mettre à jour le script (ScriptList) | Pris en charge (update-script; Réalisation scriptlist uniquement. Les appels Interprétation et Réalisation simple renvoient 409000) | Non pris en charge |
| Interroger l'historique du Travel | Pris en charge | Non pris en charge |
| Récupérer les artefacts vidéo | Pris en charge | Non pris en charge |
Le SDK n'est pas responsable de la création ou de la gestion des worlds. Le mode script Directing (Script List) n'est disponible que côté serveur ; le SDK gère uniquement le streaming, la lecture et la saisie d'instructions textuelles.
Scénarios
| Scénario | Mode recommandé | API serveur clé | Capacité clé du SDK client |
|---|---|---|---|
| Jeux interactifs / mondes jouables | Aventure | Créer un monde → échange d'identifiants | sendCommand + rappels d'état |
| Compagnon IA / guide virtuel | Aventure | Créer avec une première image + prompt | Expérience en temps réel + vue vidéo |
| Court-métrage interactif / prévisualisation de film | Réalisation | simple prompt ou scriptlist script structuré | sendInstruct + pause / rembobinage |
| Appel vidéo / compagnon en portrait | Interprétation | Requis prompt + firstFrameImage, facultatif aspectRatio | sendInstruct + pause / reprise (pas de rembobinage) |
| Plateforme de contenu / création dérivée | Réalisation | artifacts exportation après la fin de la session | Expérience + récupération d'artefacts côté serveur |
| Simulation éducative | Aventure | Construire la scène avec une première image + prompt | Expérience d'entrée en salle rapide |
Limites
- Règles de rapport d'aspect :
- Adventure :
firstFrameImageest requis ; le rapport d'aspect de la vidéo suit celui de la première image. - Directing :
firstFrameImageest optionnel dans le sous-modesimpleet requis dans le sous-modescriptlist. Lorsqu'il est fourni, il doit être au format paysage (largeur / hauteur 1.5–2.0) et le rapport d'aspect suit celui de la première image ; toute valeuraspectRatiotransmise au moment de la création est ignorée. - Interprétation :
firstFrameImageest requis ; le rapport d'aspect est contrôlé paraspectRatiolors de la création, avec9:16(portrait) par défaut, et16:9peut être transmis explicitement. Ce champ est renvoyé à l'entrée dans la salle et dans les détails du monde, et le client doit définir l'orientation du lecteur en conséquence. Le rapport d'aspect de la première image doit correspondre au rapport d'aspect cible, sinon400000est renvoyé.
- Adventure :
- Accès inter-modèles : un World et un Travel sont strictement liés au modèle qui les a créés ; l'accès inter-modèles renvoie
403001(world) ou404000(travel). - Différences de mode : le mode Acting ne prend pas en charge le rembobinage (
rewind) nisendCommand; l'appel de pause / reprise dans Adventure renvoie103003.
Glossaire
- World : une définition complète d'un monde numérique, incluant les personnages, les scènes et les scripts. Un World peut être pré-construit et réutilisé ; il constitue la base de chaque expérience.
- Travel : une session d'expérience en temps réel initiée à partir d'un World. Elle passe généralement par les étapes « initialiser → préparer → en cours → (éventuellement pause / rembobinage) → fin » ; les valeurs de statut exactes dépendent de chaque SDK — consultez la référence de l'API du SDK correspondant.
- ticket : un identifiant d'entrée en salle à usage unique émis par le serveur et délivré au client.
- token (API Key temporaire) : l'identifiant de la couche HTTP pour le SDK client, signé par le serveur et injecté dans le SDK ; doit être renouvelé périodiquement.
Vérifier Model Usage
Le module « Model Usage » dans la console ne prend pas encore en charge les statistiques d'utilisation du modèle de monde. Consultez plutôt votre utilisation via la page de facturation.
Étapes suivantes
- Démarrage rapide : réaliser l'intégration de bout en bout.