O HappyOyster é um modelo de open-world interativo em tempo real. A partir de um único prompt em linguagem natural e uma imagem do primeiro quadro, ele gera um mundo digital que você pode atuar, explorar e interagir em tempo real, entregue como um stream de vídeo ao vivo que pode ser acessado. Ideal para dramas interativos, pré-visualização de filmes, companheiros IA e worlds jogáveis.
Para vitrines de modelos e dicas de escrita de prompts, consulte o Guia do HappyOyster.
O HappyOyster oferece três modos de experiência, cada um implantado de forma independente para cobrir diferentes cenários:
O HappyOyster usa um modelo de integração servidor + cliente:
O módulo "Model Usage" no console ainda não suporta estatísticas de uso do world-model. Visualize seu uso através da página de faturamento.
Introdução
O HappyOyster oferece três modos de experiência, cada um implantado de forma independente para cobrir diferentes cenários:
| Modo | Entrada | Interação |
|---|---|---|
| Adventure | Prompt + imagem do primeiro quadro (paisagem) | Comandos direcionais / de câmera / de ação (sendCommand) |
| Directing | Prompt ou roteiro estruturado + imagem do primeiro quadro (paisagem), imagens de referência opcionais (usadas para geração de roteiro e referência de personagem) | Instruções de texto (sendInstruct) / lista de roteiros; suporta pausar, retroceder, retomar |
| Acting | Prompt + imagem do primeiro quadro (retrato 9:16 por padrão, 16:9 também suportado) | Instruções de texto (sendInstruct); suporta pausar e retomar; não suporta retroceder |
Arquitetura
O HappyOyster usa um modelo de integração servidor + cliente:
- Seu servidor gerencia todo o ciclo de vida do World por meio das Open APIs do HappyOyster (com a API Key primária, via HTTPS REST padrão): criar / gerenciar worlds, trocar credenciais e consultar histórico e artefatos. As Open APIs são divididas por modo de experiência em três suítes separadas: Adventure, Directing e Acting.
- Seu cliente oferece a experiência em tempo real por meio do SDK do HappyOyster (com uma API Key temporária +
ticket, via um canal de áudio / vídeo em tempo real RTC), com suporte para Android, iOS e Web. O SDK encapsula a conexão RTC, a reprodução de vídeo, a consulta de status e os comandos interativos, para que você não precise trabalhar diretamente com o protocolo de tempo real subjacente.
- Crie o World e obtenha as credenciais no backend. Com a API Key principal, seu backend envia
POST /worldsà Open API do HappyOyster para criar o World, consulta o status de criação comGET /worlds/build-statuse obtém as credenciais da experiência comPOST /worlds/get-travel-credential. O backend entrega otokene oticketao cliente. - Inicie a experiência em tempo real no cliente. O cliente usa o SDK, uma API Key temporária e o
ticket. ChameinitializeeupdateTokene, em seguida,startTravel(ticket). O SDK entra na experiência pela Open API, estabelece a conexão RTC e retorna ao cliente a View de vídeo e os callbacks de status. - Interaja pelo cliente. O cliente usa o SDK para chamar
sendInstruct,sendCommand,pauseouend. O SDK chama as APIs de controle correspondentes na Open API. - Obtenha os artefatos após o término da sessão. Seu backend envia
GET /travels/artifactsà Open API para obter os artefatos.
Open API e SDK
Responsabilidades
| Dimensão | Open API do HappyOyster no lado do servidor | SDK do HappyOyster no lado do cliente |
|---|---|---|
| Chamador | Seu backend | Seu aplicativo ou frontend web |
| Credenciais | API Key primária (de longo prazo, mantida apenas no servidor) | API Key temporária (token) + de uso único ticket (de curta duração) |
| Responsabilidades principais | Gerenciamento de World (criar, consultar status, consultar, excluir); troca de credenciais; controle de Travel; consulta de artefatos | Conexão RTC e renderização de vídeo; comandos de interação em tempo real; controle de sessão; callbacks de status |
| Comunicação | HTTPS REST padrão | Canal de áudio / vídeo em tempo real RTC (encapsulado dentro do SDK) |
| Plataformas suportadas | Qualquer linguagem de backend (Python, Java, Node.js, etc.) | Android, iOS, Web |
Mapa de capacidades
| Capacidade | Open API (servidor) | SDK (cliente) |
|---|---|---|
| Criar / gerenciar World | Suportado | Não suportado |
| Consultar status de compilação do world | Suportado | Não suportado |
Trocar ticket | Suportado | Não suportado (consome ticket) |
| Injetar token de autenticação HTTP | Não suportado | Suportado (updateToken) |
| Entrar na sala + conexão RTC | Suportado (invocado internamente pelo SDK) | Suportado (início do Travel, encapsulado dentro do SDK) |
| Reprodução de vídeo em tempo real | Não suportado | Suportado (anexe a visualização de vídeo fornecida pelo SDK; para Acting, use o aspectRatio retornado para definir a orientação retrato / paisagem) |
| Consulta de status | Suportado (invocado internamente pelo SDK) | Suportado (exposto via callbacks de status) |
| Instruções de texto para Directing / Acting | Suportado (instruct) | Suportado (sendInstruct) |
| Comandos de controle do Adventure | Não suportado | Suportado (sendCommand; não disponível no Acting) |
| Pausar / retomar | Suportado | Suportado (Directing e Acting; chamadas do Adventure são rejeitadas pelo SDK com 103003) |
| Retroceder | Suportado (rewind; apenas Directing) | Suportado (apenas Directing; outros modos são rejeitados com 103003) |
| Encerrar a experiência | Suportado | Suportado (fim do Travel, encapsulado dentro do SDK) |
| Atualizar roteiro (ScriptList) | Suportado (update-script; Directing scriptlist apenas. Acting e Directing simple retornam 409000) | Não suportado |
| Consultar histórico do Travel | Suportado | Não suportado |
| Recuperar artefatos de vídeo | Suportado | Não suportado |
O SDK não é responsável por criar ou gerenciar worlds. O modo de roteiro Directing (Script List) está disponível apenas no lado do servidor; o SDK lida apenas com streaming, reprodução e entrada de instruções de texto.
Cenários
| Cenário | Modo Recomendado | API principal do servidor | Capacidade principal do SDK cliente |
|---|---|---|---|
| Jogos interativos / worlds jogáveis | Adventure | Criar world → troca de credenciais | sendCommand + callbacks de status |
| Companheiro IA / guia virtual | Adventure | Criar com imagem do primeiro quadro + prompt | Experiência em tempo real + visualização de vídeo |
| Curta-metragem interativo / pré-visualização de filme | Directing | simple prompt ou scriptlist roteiro estruturado | sendInstruct + pausar / retroceder |
| Videochamada / companheiro em retrato | Acting | Obrigatório prompt + firstFrameImage, opcional aspectRatio | sendInstruct + pausar / retomar (sem retroceder) |
| Plataforma de conteúdo / criação derivada | Directing | artifacts exportar após o fim da sessão | Experiência + recuperação de artefatos no lado do servidor |
| Simulação educacional | Adventure | Construir a cena com uma imagem do primeiro quadro + prompt | Experiência de entrada rápida na sala |
Limitações
- Regras de proporção de tela:
- Adventure:
firstFrameImageé obrigatório; a proporção de tela do vídeo segue a imagem do primeiro quadro. - Directing:
firstFrameImageé opcional no submodosimplee obrigatório no submodoscriptlist. Quando fornecido, deve ser paisagem (largura / altura 1.5–2.0) e a proporção segue a imagem do primeiro quadro; qualquer valor deaspectRatiopassado no momento da criação é ignorado. - Acting:
firstFrameImageé obrigatório; a proporção é controlada poraspectRationo momento da criação, com padrão9:16(retrato), e16:9pode ser passado explicitamente. Este campo é retornado na entrada da sala e nos detalhes do world, e o cliente deve definir a orientação do player de acordo. A proporção do primeiro quadro deve corresponder à proporção alvo, caso contrário,400000é retornado.
- Adventure:
- Acesso entre modelos: Um World e um Travel estão estritamente vinculados ao modelo que os criou; o acesso entre modelos retorna
403001(world) ou404000(travel). - Diferenças de modo: Acting não suporta retrocesso (
rewind) ousendCommand; chamar pausa / retomada em Adventure retorna103003.
Glossário
- World: Uma definição completa de um mundo digital, incluindo personagens, cenários e roteiros. Um World pode ser pré-construído e reutilizado; é a base de cada experiência.
- Travel: Uma sessão de experiência em tempo real iniciada a partir de um World. Ela geralmente passa pelas etapas "inicializar → preparar → em execução → (opcionalmente pausar / retroceder) → encerrar"; os valores exatos de status variam por SDK — consulte a referência de API do SDK correspondente.
- ticket: Uma credencial de entrada na sala de uso único emitida pelo servidor e entregue ao cliente.
- token (API Key temporária): A credencial da camada HTTP para o SDK cliente, assinada pelo servidor e injetada no SDK; deve ser renovada periodicamente.
Verificar Model Usage
O módulo "Model Usage" no console ainda não suporta estatísticas de uso do world-model. Visualize seu uso através da página de faturamento.
Próximos passos
- Início rápido: Conclua a integração de ponta a ponta.