Crie um Mundo de role-play. Crie um Mundo a partir de um prompt em linguagem natural e uma imagem de primeiro quadro obrigatória; a API retorna imediatamente um ID de Mundo criptografado (encryptedWorldId), o Mundo é construído assincronamente em segundo plano, e o cliente consulta o progresso da construção até sua conclusão.
Escopo
Crie um Mundo de Atuação. Antes de chamar, confirme o seguinte:
-
Autenticação: Apenas a API Key primária é suportada; API Keys temporárias não podem ser usadas (código de erro
403003).- Obtenha a API Key primária: Obter e configurar uma API Key.
-
Modo de chamada: Recomenda-se o modo assíncrono.
- Modo assíncrono (padrão):
async=true, a API retorna imediatamenteencryptedWorldId; consulte Consultar Status de Construção do Mundo para verificar o progresso. - Modo síncrono:
async=false, o servidor consulta internamente (a cada 3s, até 120s) e retorna quando a construção for concluída; em caso de tempo limite, reverte para assíncrono e o cliente continua consultando.
- Modo assíncrono (padrão):
-
Restrições do endpoint: Este endpoint só pode criar um Mundo de Atuação. Você não precisa passar
mode(o servidor grava3; passar um valor diferente de3retorna400000).creationModelé sempresimple,uploadModeé fixo emfirst_frame, e a versão de entrada na sala é fixa emactingV2.
Solicitação HTTP
- Singapore
- EUA (Virgínia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worldsSubstitua {WorkspaceId} pelo seu ID do Workspace real.Parâmetros da solicitação |
|
Content-Typestring(Obrigatório)Tipo de conteúdo da solicitação. Este parâmetro deve ser definido como application/json. | |
Authorization string (Obrigatório)Autenticação por API Key. Apenas a API Key primária é suportada; ela começa com sk-, ex. sk-xxx. É tipicamente configurada como a variável de ambiente $DASHSCOPE_API_KEY. Uma API Key temporária (começando com st-) retorna 403003. | |
Corpo da solicitação | |
async boolean (Opcional)Se deve criar de forma assíncrona. O padrão é true:
| |
creationModel string (Opcional)Submodo de criação. O padrão é simple; Acting suporta apenas simple. | |
prompt string (Obrigatório)Uma descrição em linguagem natural do personagem, cenário e objetivo da performance. Não vazia, até 2000 caracteres. Ausente, em branco ou excedendo o limite retorna 400000. | |
uploadMode string (Opcional)Modo de upload de imagem. O padrão é first_frame; Acting suporta apenas first_frame. | |
resolution string (Opcional)Resolução do vídeo. O padrão é 480p. Valores permitidos:
| |
aspectRatio string (Opcional)Proporção de quadros de streaming, que também determina a orientação da imagem do primeiro quadro; recomenda-se manter as duas consistentes. O padrão é 9:16. Valores permitidos:
9:16) passe um primeiro quadro em retrato, e para streaming em paisagem (16:9) passe um primeiro quadro em paisagem. O padrão é 9:16; quando a paisagem for necessária, você deve passar explicitamente aspectRatio=16:9. | |
refWorldId string (Opcional)Derivar uma nova criação a partir de um Mundo de Atuação existente. Deve ser um ID de Mundo de Atuação criptografado sob a conta primária atual; um Mundo de outro modelo ou de outra conta primária retorna 403001. | |
firstFrameImage object (Obrigatório)Uma referência de imagem reutilizada como o primeiro quadro do Mundo. url e base64 são mutuamente exclusivos (escolha um). Restrições da imagem:
Propriedades url string (Condicionalmente obrigatório)URL da imagem do primeiro quadro. Mutuamente exclusivo com base64 (escolha um). Restrições:
string (Condicionalmente obrigatório)Base64 da imagem do primeiro quadro. Mutuamente exclusivo com url (escolha um). Restrições:
string (Opcional)Tipo de referência do primeiro quadro. O padrão é default, e atualmente é usado como default. |
Parâmetros de resposta |
|
code integerCódigo de retorno. 0 indica sucesso; diferente de zero é um código de erro. | |
message stringMensagem de erro. null em caso de sucesso; uma mensagem de erro legível por humanos em caso de falha. | |
data objectDados da resposta. null em caso de falha.
Propriedades encryptedWorldId stringO ID do Mundo criptografado gerado pelo servidor. Retornado tanto nos modos síncrono quanto assíncrono; usado para consultas subsequentes de status de construção, detalhes e troca de credencial de viagem.status stringStatus atual da criação:
stringURL do primeiro quadro do Mundo; null antes de ser gerado. |
Códigos de erro
Se a chamada do modelo falhar e retornar um erro, consulte Códigos de Erro do HappyOyster para resolvê-lo.
Próximos passos
Após criar com sucesso, você pode:
- Consultar Status de Construção do Mundo: consulte a cada 3–5 segundos até que o Mundo entre em
ready. - Depois que o Mundo entrar em
ready, chame Obter Credencial de Viagem para trocar por umticketde uso único. - Consultar Detalhes do Mundo: consulte os metadados completos da criação.