Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Visão geral

HappyOyster é um modelo de mundo aberto interativo em tempo real. A partir de um único prompt em linguagem natural e uma imagem de primeiro quadro, ele gera um mundo digital no qual você pode atuar, explorar e interagir em tempo real, entregue como uma transmissão de vídeo ao vivo juntável. Adequado para drama interativo, pré-visualização de filmes, companheiros de IA e mundos jogáveis.

Introdução

HappyOyster oferece três modos de experiência, cada um implementado de forma independente para cobrir diferentes cenários:

Modo	Entrada	Interação
Aventura	Prompt + imagem do primeiro quadro (paisagem)	Comandos direcionais/câmera/ação (`sendCommand`)
Direção	Script pronto ou estruturado + imagem do primeiro quadro (paisagem), imagens de referência opcionais (usadas para geração de script e referência de personagem)	Instruções de texto (`sendInstruct`)/lista de scripts; suporta pausar, retroceder, retomar
Atuação	Prompt + imagem do primeiro quadro (retrato `9:16` por padrão, `16:9` também suportado)	Instruções de texto (`sendInstruct`); suporta pausa e retomada; não suporta retrocesso

Arquitetura

HappyOyster usa um servidor + cliente modelo de integração:

Seu servidor gerencia todo o ciclo de vida mundial através do HappyOyster APIs abertas (com a chave de API primária, sobre REST HTTPS padrão): crie/gerencie mundos, troque credenciais e consulte histórico e artefatos. As APIs abertas são divididas por modo de experiência em três conjuntos separados: Aventura, Direção e Atuação.
Seu cliente oferece a experiência em tempo real através do HappyOyster SDK (com uma chave de API temporária + ticket, através de um canal de áudio/vídeo RTC em tempo real), com suporte para Android, iOS e Web. O SDK encapsula a conexão RTC, a reprodução de vídeo, a pesquisa de status e os comandos interativos, para que você não precise trabalhar diretamente com o protocolo subjacente em tempo real.

Todos os endpoints são autenticados através do Alibaba Cloud QwenCloud portal. Para obter o modelo de credenciais e como obtê-las, consulte Obter credenciais de autenticação.

Abra API e SDK

Responsabilidades

Dimensão	Lado do servidor HappyOyster API aberta	Lado do cliente HappyOyster SDK
Chamador	Seu back-end	Seu aplicativo ou interface web
Credenciais	Chave API primária (longo prazo, mantida apenas no servidor)	Chave de API temporária (token) + única `ticket` (de curta duração)
Responsabilidades principais	Gerenciamento mundial (criar, pesquisar status, consultar, excluir); troca de credenciais; Controle de viagens; consulta de artefato	Conexão RTC e renderização de vídeo; comandos de interação em tempo real; controle de sessão; retornos de chamada de status
Comunicação	REST HTTPS padrão	Canal de áudio/vídeo RTC em tempo real (encapsulado dentro do SDK)
Plataformas suportadas	Qualquer linguagem de backend (Python, Java, Node.js, etc.)	Android, iOS, Web

Mapa de capacidade

Capacidade	API aberta (servidor)	SDK (cliente)
Criar/gerenciar mundo	Suportado	Não suportado
Status de construção mundial da pesquisa	Suportado	Não suportado
Troca `ticket`	Suportado	Não suportado (consome `ticket`)
Injetar token de autenticação HTTP	Não suportado	Suportado (`updateToken`)
Entrar na sala + conexão RTC	Compatível (invocado internamente pelo SDK)	Suportado (início de viagem, encapsulado dentro do SDK)
Reprodução de vídeo em tempo real	Não suportado	Compatível (anexe a visualização de vídeo fornecida pelo SDK; para Atuação, use o retornado `aspectRatio` para definir a orientação retrato/paisagem)
Pesquisa de status	Compatível (invocado internamente pelo SDK)	Suportado (aparecido por meio de retornos de chamada de status)
Instruções de texto para direção/atuação	Suportado (`instruct`)	Suportado (`sendInstruct`)
Comandos de controle de aventura	Não suportado	Suportado (`sendCommand`; não disponível em Atuação)
Pausar/retomar	Suportado	Suportado (direção e atuação; chamadas de aventura são rejeitadas pelo SDK com `103003`)
Retroceder	Suportado (`rewind`; Somente direção)	Suportado (somente Direção; outros modos são rejeitados com `103003`)
Terminar a experiência	Suportado	Suportado (fim da viagem, encapsulado dentro do SDK)
Atualizar script (ScriptList)	Suportado (`update-script`; Direção `scriptlist` apenas. Atuação e direção `simple` retorno de chamadas `409000`)	Não suportado
Consultar histórico de viagem	Suportado	Não suportado
Recuperar artefatos de vídeo	Suportado	Não suportado

O SDK é não é responsável para criar ou gerenciar mundos. O modo Directing script (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 do servidor chave	Capacidade principal do SDK do cliente
Jogos interativos/mundos jogáveis	Aventura	Criar mundo → troca de credenciais	`sendCommand` + retornos de chamada de status
Companheiro de IA / guia virtual	Aventura	Criar com imagem do primeiro quadro + prompt	Experiência em tempo real + visualização de vídeo
Pré-visualização interativa de curta-metragem / drama	Direção	`simple` alertar ou `scriptlist` roteiro estruturado	`sendInstruct` + pausar/retroceder
Acompanhante de videochamada / retrato	Atuação	Obrigatório `prompt` + `firstFrameImage`, opcional `aspectRatio`	`sendInstruct` + pausar/resumir (sem retrocesso)
Plataforma de conteúdo/criação de derivados	Direção	`artifacts` exportar após o término da sessão	Experiência + recuperação de artefatos do lado do servidor
Simulação educacional	Aventura	Construa a cena com uma imagem de primeiro quadro + prompt	Experiência de entrada rápida na sala

Limitações

Regras de proporção:
- Aventura: firstFrameImage é obrigatório; a proporção do vídeo segue a imagem do primeiro quadro.
- Direção: firstFrameImage é opcional em simple submodo e exigido em scriptlist submodo. Quando fornecido, deve ser paisagem (largura/altura 1,5–2,0) e a proporção segue a imagem do primeiro quadro; qualquer aspectRatio o valor passado no momento da criação é ignorado.
- Atuação: firstFrameImage é obrigatório; a proporção de aspecto é controlada por aspectRatio no momento da criação, padronizando para 9:16 (retrato) e 16:9 pode ser passado explicitamente. Este campo é repetido na entrada da sala e nos detalhes do mundo, e o cliente deve definir a orientação do jogador de acordo. A proporção do primeiro quadro deve corresponder à proporção de destino, caso contrário 400000 é retornado.
Acesso entre modelos: Um Mundo e uma Viagem estão estritamente vinculados ao modelo que os criou; retornos de acesso entre modelos 403001 (mundo) ou 404000 (viagem).
Diferenças de modo: A atuação não suporta retrocesso (rewind) ou sendCommand; chamando pausa / currículo em retornos de aventura 103003.

Glossário

Mundo: uma definição completa de um mundo digital, incluindo personagens, cenas e roteiros. Um mundo pode ser pré-construído e reutilizado; é a base de toda experiência.
Viagem: uma sessão de experiência em tempo real iniciada em um mundo. Geralmente passa pelos estágios "inicializar → preparar → executar → (opcionalmente pausar/retroceder) → finalizar"; os valores exatos de status são por SDK — consulte a referência correspondente da API do SDK.
ticket: uma credencial única de entrada na sala emitida pelo servidor e entregue ao cliente.
token (chave de API temporária): a credencial da camada HTTP para o SDK do cliente, assinada pelo servidor e injetada no SDK; devem ser renovados periodicamente.

Verifique o uso do modelo

O módulo “Model Usage” do console ainda não cobre estatísticas de uso do modelo mundial. Veja seu uso na página Gerenciamento de faturamento e custos página em vez disso.

Próximas etapas

Início rápido: Conclua a integração ponta a ponta.