HappyOyster es un modelo de mundo abierto interactivo en tiempo real. A partir de un único prompt en lenguaje natural y una imagen del primer fotograma, genera un mundo digital con el que puede actuar, explorar e interactuar en tiempo real, entregado como una transmisión de video en vivo a la que se puede unir. Es ideal para dramas interactivos, previsualización cinematográfica, compañeros de IA y mundos jugables.
Para exhibiciones de modelos y consejos sobre redacción de prompts, consulte la Guía de HappyOyster.
Introducción
HappyOyster ofrece tres modos de experiencia, cada uno desplegado de forma independiente para cubrir diferentes escenarios:
| Modo | Entrada | Interacción |
|---|---|---|
| Adventure | Prompt + imagen del primer fotograma (horizontal) | Comandos direccionales / de cámara / de acción (sendCommand) |
| Dirección | Prompt o guion estructurado + imagen del primer fotograma (horizontal), imágenes de referencia opcionales (utilizadas para la generación de guiones y referencia de personajes) | Instrucciones de texto (sendInstruct) / lista de guiones; admite pausa, rebobinado y reanudación |
| Acting | Prompt + imagen del primer fotograma (vertical 9:16 de forma predeterminada, 16:9 también admitido) | Instrucciones de texto (sendInstruct); admite pausa y reanudación; no admite rebobinado |
Arquitectura
HappyOyster utiliza un modelo de integración servidor + cliente:
- Su servidor gestiona todo el ciclo de vida del Mundo a través de las Open API de HappyOyster (con la clave API principal, mediante HTTPS REST estándar): crear y gestionar mundos, intercambiar credenciales y consultar el historial y los artefactos. Las Open API se dividen según el modo de experiencia en tres conjuntos separados: Aventura, Dirección y Actuación.
- Su cliente ofrece la experiencia en tiempo real a través del SDK de HappyOyster (con una clave API temporal +
ticket, mediante un canal de audio/video en tiempo real RTC), compatible con Android, iOS y Web. El SDK encapsula la conexión RTC, la reproducción de video, el sondeo de estado y los comandos interactivos, por lo que no necesita trabajar directamente con el protocolo subyacente en tiempo real.
Todos los endpoints se autentican a través de la puerta de enlace de Alibaba Cloud Model Studio. Para conocer el modelo de credenciales y cómo obtenerlas, consulte Obtener credenciales de autenticación.
Open API y SDK
Responsabilidades
| Dimensión | Open API de HappyOyster del lado del servidor | SDK de HappyOyster del lado del cliente |
|---|---|---|
| Solicitante | Su backend | Su aplicación o frontend web |
| Credenciales | Clave API principal (a largo plazo, almacenada solo en el servidor) | Clave API temporal (token) + ticket (de corta duración) |
| Responsabilidades principales | Gestión de mundos (crear, sondear estado, consultar, eliminar); intercambio de credenciales; control de Viaje; consulta de artefactos | Conexión RTC y renderizado de video; comandos de interacción en tiempo real; control de sesión; callbacks de estado |
| Comunicación | HTTPS REST estándar | Canal de audio/video en tiempo real RTC (encapsulado dentro del SDK) |
| Plataformas compatibles | Cualquier lenguaje de backend (Python, Java, Node.js, etc.) | Android, iOS, Web |
Mapa de capacidades
| Capacidad | Open API (servidor) | SDK (cliente) |
|---|---|---|
| Crear / gestionar Mundo | Compatible | No compatible |
| Sondear estado de construcción del mundo | Compatible | No compatible |
Intercambiar ticket | Compatible | No admitido (consume ticket) |
| Inyectar token de autenticación HTTP | No compatible | Admitido (updateToken) |
| Entrar a la sala + conexión RTC | Admitido (invocado internamente por el SDK) | Admitido (inicio de Viaje, encapsulado dentro del SDK) |
| Reproducción de video en tiempo real | No compatible | Admitido (adjuntar la vista de video proporcionada por el SDK; para Actuación, utilice el aspectRatio devuelto para establecer la orientación vertical / horizontal) |
| Sondeo de estado | Admitido (invocado internamente por el SDK) | Admitido (expuesto mediante callbacks de estado) |
| Instrucciones de texto de Dirección / Actuación | Admitido (instruct) | Admitido (sendInstruct) |
| Comandos de control de Aventura | No compatible | Admitido (sendCommand; no disponible en Actuación) |
| Pausa / reanudación | Compatible | Admitido (Dirección y Actuación; las llamadas de Aventura son rechazadas por el SDK con 103003) |
| Rebobinar | Admitido (rewind; solo Dirección) | Admitido (solo Dirección; otros modos se rechazan con 103003) |
| Finalizar la experiencia | Compatible | Admitido (fin de Viaje, encapsulado dentro del SDK) |
| Actualizar guion (ScriptList) | Admitido (update-script; Dirección scriptlist únicamente. Actuación y Dirección simple devuelven 409000) | No compatible |
| Consultar historial de Viaje | Compatible | No compatible |
| Recuperar artefactos de video | Compatible | No compatible |
NotaEl SDK no es responsable de crear ni gestionar mundos. El modo de guion de dirección (Lista de guiones) solo está disponible en el lado del servidor; el SDK únicamente gestiona la transmisión por streaming, la reproducción y la entrada de instrucciones de texto.
Escenarios
| Escenario | Modo recomendado | API clave del servidor | Capacidad clave del SDK cliente |
|---|---|---|---|
| Juegos interactivos / mundos jugables | Adventure | Crear mundo → intercambio de credenciales | sendCommand + callbacks de estado |
| Compañero IA / guía virtual | Adventure | Crear con imagen del primer fotograma + prompt | Experiencia en tiempo real + vista de video |
| Drama corto interactivo / previsualización cinematográfica | Dirección | simple prompt o scriptlist guion estructurado | sendInstruct + pausa / rebobinado |
| Videollamada / compañero vertical | Acting | Obligatorio prompt + firstFrameImage, opcional aspectRatio | sendInstruct + pausa / reanudación (sin rebobinado) |
| Plataforma de contenido / creación derivada | Dirección | artifacts exportación después de que finalice la sesión | Experiencia + recuperación de artefactos del lado del servidor |
| Simulación educativa | Adventure | Construir la escena con una imagen del primer fotograma + prompt | Experiencia de entrada rápida a la sala |
Limitaciones
- Reglas de relación de aspecto:
- Adventure:
firstFrameImagees obligatorio; la relación de aspecto del video sigue a la imagen del primer fotograma. - Dirección:
firstFrameImagees opcional en el submodosimpley obligatorio en el submodoscriptlist. Cuando se proporciona, debe ser horizontal (ancho / alto 1.5–2.0) y la relación de aspecto sigue a la imagen del primer fotograma; cualquier valor deaspectRatiopasado en el momento de la creación se ignora. - Actuación:
firstFrameImagees obligatorio; la relación de aspecto se controla medianteaspectRatioen el momento de la creación, con un valor predeterminado de9:16(vertical), y se puede pasar16:9explícitamente. Este campo se refleja al entrar a la sala y en los detalles del mundo, y el cliente debe configurar la orientación del reproductor en consecuencia. La relación de aspecto del primer fotograma debe coincidir con la relación de aspecto objetivo; de lo contrario, se devuelve400000.
- Adventure:
- Acceso entre modelos: Un World y un Travel están estrictamente vinculados al modelo que los creó; el acceso entre modelos devuelve
403001(world) o404000(travel). - Diferencias entre modos: Acting no admite rebobinado (
rewind) nisendCommand; llamar a pausa / reanudación en Adventure devuelve103003.
Glosario
- World: Una definición completa de un mundo digital, que incluye personajes, escenas y guiones. Un World puede preconstruirse y reutilizarse; es la base de cada experiencia.
- Viaje: Una sesión de experiencia en tiempo real iniciada desde un Mundo. Generalmente pasa por las etapas "inicializar → preparar → en ejecución → (opcionalmente pausar / rebobinar) → finalizar"; los valores de estado exactos dependen de cada SDK; consulte la referencia de API del SDK correspondiente.
- ticket: Una credencial de entrada a la sala de un solo uso emitida por el servidor y entregada al cliente.
- token (API Key temporal): La credencial de capa HTTP para el SDK del cliente, firmada por el servidor e inyectada en el SDK; debe renovarse periódicamente.
Consultar Model Usage
El módulo "Model Usage" en la consola aún no admite estadísticas de uso de modelos de mundo. Consulte su uso a través de la página de facturación.
Siguientes pasos
-
Inicio rápido: Complete la integración de extremo a extremo.