Skip to main content

Visão geral

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.

Introdução

O HappyOyster oferece três modos de experiência, cada um implantado de forma independente para cobrir diferentes cenários:
ModoEntradaInteração
AdventurePrompt + imagem do primeiro quadro (paisagem)Comandos direcionais / de câmera / de ação (sendCommand)
DirectingPrompt 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
ActingPrompt + 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.
O fluxo envolve o usuário final, seu aplicativo cliente ou Web, seu backend, a Open API do HappyOyster e o SDK do HappyOyster. Integre nesta ordem:
  1. 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 com GET /worlds/build-status e obtém as credenciais da experiência com POST /worlds/get-travel-credential. O backend entrega o token e o ticket ao cliente.
  2. Inicie a experiência em tempo real no cliente. O cliente usa o SDK, uma API Key temporária e o ticket. Chame initialize e updateToken e, 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.
  3. Interaja pelo cliente. O cliente usa o SDK para chamar sendInstruct, sendCommand, pause ou end. O SDK chama as APIs de controle correspondentes na Open API.
  4. Obtenha os artefatos após o término da sessão. Seu backend envia GET /travels/artifacts à Open API para obter os artefatos.
Todos os endpoints são autenticados por meio do gateway do Alibaba Cloud Model Studio. Para o modelo de credenciais e como obtê-las, consulte Obter credenciais de autenticação.

Open API e SDK

Responsabilidades

DimensãoOpen API do HappyOyster no lado do servidorSDK do HappyOyster no lado do cliente
ChamadorSeu backendSeu aplicativo ou frontend web
CredenciaisAPI Key primária (de longo prazo, mantida apenas no servidor)API Key temporária (token) + de uso único ticket (de curta duração)
Responsabilidades principaisGerenciamento de World (criar, consultar status, consultar, excluir); troca de credenciais; controle de Travel; consulta de artefatosConexão RTC e renderização de vídeo; comandos de interação em tempo real; controle de sessão; callbacks de status
ComunicaçãoHTTPS REST padrãoCanal de áudio / vídeo em tempo real RTC (encapsulado dentro do SDK)
Plataformas suportadasQualquer linguagem de backend (Python, Java, Node.js, etc.)Android, iOS, Web

Mapa de capacidades

CapacidadeOpen API (servidor)SDK (cliente)
Criar / gerenciar WorldSuportadoNão suportado
Consultar status de compilação do worldSuportadoNão suportado
Trocar ticketSuportadoNão suportado (consome ticket)
Injetar token de autenticação HTTPNão suportadoSuportado (updateToken)
Entrar na sala + conexão RTCSuportado (invocado internamente pelo SDK)Suportado (início do Travel, encapsulado dentro do SDK)
Reprodução de vídeo em tempo realNão suportadoSuportado (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 statusSuportado (invocado internamente pelo SDK)Suportado (exposto via callbacks de status)
Instruções de texto para Directing / ActingSuportado (instruct)Suportado (sendInstruct)
Comandos de controle do AdventureNão suportadoSuportado (sendCommand; não disponível no Acting)
Pausar / retomarSuportadoSuportado (Directing e Acting; chamadas do Adventure são rejeitadas pelo SDK com 103003)
RetrocederSuportado (rewind; apenas Directing)Suportado (apenas Directing; outros modos são rejeitados com 103003)
Encerrar a experiênciaSuportadoSuportado (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 TravelSuportadoNão suportado
Recuperar artefatos de vídeoSuportadoNã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árioModo RecomendadoAPI principal do servidorCapacidade principal do SDK cliente
Jogos interativos / worlds jogáveisAdventureCriar world → troca de credenciaissendCommand + callbacks de status
Companheiro IA / guia virtualAdventureCriar com imagem do primeiro quadro + promptExperiência em tempo real + visualização de vídeo
Curta-metragem interativo / pré-visualização de filmeDirectingsimple prompt ou scriptlist roteiro estruturadosendInstruct + pausar / retroceder
Videochamada / companheiro em retratoActingObrigatório prompt + firstFrameImage, opcional aspectRatiosendInstruct + pausar / retomar (sem retroceder)
Plataforma de conteúdo / criação derivadaDirectingartifacts exportar após o fim da sessãoExperiência + recuperação de artefatos no lado do servidor
Simulação educacionalAdventureConstruir a cena com uma imagem do primeiro quadro + promptExperiê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 submodo simple e obrigatório no submodo scriptlist. Quando fornecido, deve ser paisagem (largura / altura 1.5–2.0) e a proporção segue a imagem do primeiro quadro; qualquer valor de aspectRatio passado no momento da criação é ignorado.
    • Acting: firstFrameImage é obrigatório; a proporção é controlada por aspectRatio no momento da criação, com padrão 9:16 (retrato), e 16:9 pode 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.
  • Acesso entre modelos: Um World e um Travel estão estritamente vinculados ao modelo que os criou; o acesso entre modelos retorna 403001 (world) ou 404000 (travel).
  • Diferenças de modo: Acting não suporta retrocesso (rewind) ou sendCommand; chamar pausa / retomada em Adventure retorna 103003.

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