Skip to main content

Présentation

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.

Introduction

HappyOyster propose trois modes d'expérience, chacun déployé indépendamment pour couvrir différents scénarios :
ModeEntréeInteraction
AventurePrompt + première image (paysage)Commandes directionnelles / de caméra / d'action (sendCommand)
RéalisationPrompt 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étationPrompt + 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.
Ce flux implique l'utilisateur final, votre application cliente ou Web, votre backend, l'Open API HappyOyster et le SDK HappyOyster. Procédez dans cet ordre :
  1. 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 avec GET /worlds/build-status, puis obtient les identifiants de l'expérience avec POST /worlds/get-travel-credential. Le backend transmet le token et le ticket au client.
  2. 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 appelle initialize et updateToken, puis startTravel(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.
  3. Interagissez depuis le client. Le client passe par le SDK pour appeler sendInstruct, sendCommand, pause ou end. Le SDK appelle les API de contrôle correspondantes de l'Open API.
  4. Récupérez les artefacts après la session. Votre backend envoie GET /travels/artifacts à l'Open API pour récupérer les artefacts.
Tous les points de terminaison sont authentifiés via la passerelle Alibaba Cloud Model Studio. Pour le modèle d'identifiants et la manière de les obtenir, consultez Obtenir les identifiants d'authentification.

Open API et SDK

Responsabilités

DimensionOpen API HappyOyster côté serveurSDK HappyOyster côté client
AppelantVotre backendVotre application ou frontend web
IdentifiantsClé API principale (à long terme, conservée uniquement sur le serveur)Clé API temporaire (token) + à usage unique ticket (à courte durée de vie)
Responsabilités principalesGestion du monde (création, interrogation d'état, requête, suppression) ; échange d'identifiants ; contrôle du Travel ; requête d'artefactsConnexion RTC et rendu vidéo ; commandes d'interaction en temps réel ; contrôle de session ; rappels d'état
CommunicationHTTPS REST standardCanal audio/vidéo en temps réel RTC (encapsulé dans le SDK)
Plateformes prises en chargeTout 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 mondePris en chargeNon pris en charge
Interroger l'état de construction du mondePris en chargeNon pris en charge
Échanger ticketPris en chargeNon pris en charge (consomme ticket)
Injecter le token d'authentification HTTPNon pris en chargePris en charge (updateToken)
Entrer dans la salle + connexion RTCPris 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éelNon pris en chargePris 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'étatPris en charge (invoqué en interne par le SDK)Pris en charge (affiché via les rappels d'état)
Instructions textuelles pour Réalisation / InterprétationPris en charge (instruct)Pris en charge (sendInstruct)
Commandes de contrôle AventureNon pris en chargePris en charge (sendCommand; non disponible en Interprétation)
Pause / reprisePris en chargePris en charge (Réalisation et Interprétation ; les appels Aventure sont rejetés par le SDK avec 103003)
RembobinagePris en charge (rewind; Réalisation uniquement)Pris en charge (Réalisation uniquement ; les autres modes sont rejetés avec 103003)
Terminer l'expériencePris en chargePris 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 TravelPris en chargeNon pris en charge
Récupérer les artefacts vidéoPris en chargeNon 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énarioMode recommandéAPI serveur cléCapacité clé du SDK client
Jeux interactifs / mondes jouablesAventureCréer un monde → échange d'identifiantssendCommand + rappels d'état
Compagnon IA / guide virtuelAventureCréer avec une première image + promptExpérience en temps réel + vue vidéo
Court-métrage interactif / prévisualisation de filmRéalisationsimple prompt ou scriptlist script structurésendInstruct + pause / rembobinage
Appel vidéo / compagnon en portraitInterprétationRequis prompt + firstFrameImage, facultatif aspectRatiosendInstruct + pause / reprise (pas de rembobinage)
Plateforme de contenu / création dérivéeRéalisationartifacts exportation après la fin de la sessionExpérience + récupération d'artefacts côté serveur
Simulation éducativeAventureConstruire la scène avec une première image + promptExpérience d'entrée en salle rapide

Limites

  • Règles de rapport d'aspect :
    • Adventure : firstFrameImage est requis ; le rapport d'aspect de la vidéo suit celui de la première image.
    • Directing : firstFrameImage est optionnel dans le sous-mode simple et requis dans le sous-mode scriptlist. 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 valeur aspectRatio transmise au moment de la création est ignorée.
    • Interprétation : firstFrameImage est requis ; le rapport d'aspect est contrôlé par aspectRatio lors de la création, avec 9:16 (portrait) par défaut, et 16:9 peut ê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, sinon 400000 est renvoyé.
  • 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) ou 404000 (travel).
  • Différences de mode : le mode Acting ne prend pas en charge le rembobinage (rewind) ni sendCommand ; l'appel de pause / reprise dans Adventure renvoie 103003.

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