Crie um Mundo de direção em tempo real. Suporta o modo padrão (prompt em linguagem natural) e o modo de script (ScriptList estruturado); a API retorna imediatamente um ID de Mundo criptografado, o Mundo é construído de forma assíncrona em segundo plano e o cliente consulta o progresso da construção até que ela seja concluída.
Escopo
Crie um Mundo de Direçã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 Direção. Você não precisa passar
mode(o servidor grava2; passar um valor diferente de2retorna400000).creationModelsuportasimple(modo padrão, padrão) escriptlist(modo de roteiro); a versão de entrada na sala é fixa emstoryV2, easpectRatioemaxExperienceTimeSecsão fixos emnull.
Solicitação HTTP
- Singapore
- EUA (Virgínia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worldsSubstitua {WorkspaceId} pelo seu ID do Workspace real.Modo padrão (creationModel=simple)
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; passe simple para o modo padrão (padrão). Você fornece um prompt em linguagem natural, e o servidor gera o roteiro completo de 45 beats, o primeiro quadro (que você pode fornecer) e imagens de referência de personagens. Após a criação do Mundo, você pode chamar os seguintes endpoints de controle durante a fase de Viagem:
| |
eventStyle string (Opcional)Aplica-se apenas a creationModel=simple: seleciona o modelo de geração de roteiro. O padrão é normal. Valores permitidos:
| |
refWorldId string (Opcional)Derivar uma nova criação de um Mundo de Direção existente. Deve ser um ID de Mundo de Direção criptografado sob a conta primária atual; um Mundo de outro modelo ou de outra conta primária retorna 403001. | |
prompt string (Obrigatório)Descrição do tema do mundo; chinês e inglês são suportados. Não vazio, até 2000 caracteres. | |
resolution string (Obrigatório)Resolução do vídeo. Valores permitidos:
| |
layout string (Opcional)Estilo de movimento da câmera (como a câmera se move e quão bruscos são os cortes). Valores permitidos:
| |
narrative string (Opcional)Estilo narrativo (quão denso é o drama e quão forte é a emoção). Valores permitidos:
| |
firstFrameImage object (Opcional)Quando fornecido, é reutilizado diretamente como o primeiro quadro do Mundo, pulando a geração do primeiro quadro por IA. url e base64 são mutuamente exclusivos (escolha um). Restrições de imagem:
Propriedades url string (Condicionalmente obrigatório)URL da imagem do primeiro quadro. Restrições:
string (Condicionalmente obrigatório)Base64 da imagem do primeiro quadro. Restrições:
string (Opcional)Tipo de imagem de referência. O padrão é default. | |
inputImages array (Opcional)Usado para geração de roteiro e imagens de referência de personagens, até 6 imagens, independente de firstFrameImage. Para cada item do array, url e base64 são mutuamente exclusivos (escolha um). Restrições de imagem:
Propriedades url string (Condicionalmente obrigatório)URL da imagem. Restrições:
string (Condicionalmente obrigatório)Base64 da imagem. Restrições:
string (Opcional)Tipo de imagem de referência. O padrão é default. |
Modo de roteiro (creationModel=scriptlist)
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; passe scriptlist para o modo de roteiro. Você fornece o roteiro estruturado, e o servidor não gera mais um roteiro — ele apenas o monta e persiste. Após a criação do Mundo, você pode chamar os seguintes endpoints de controle durante a fase de Viagem:
instruct (enviar instruções de processo de texto) não é suportado. Consulte Notas adicionais para obter uma descrição de cada endpoint.eventStyle não é consumido pela criação do scriptlist; não o passe. | |
refWorldId string (Opcional)Derivar uma nova criação de um Mundo de Direção existente. Deve ser um ID de Mundo de Direção criptografado sob a conta primária atual; um Mundo de outro modelo ou de outra conta primária retorna 403001. | |
resolution string (Obrigatório)Resolução do vídeo. Valores permitidos:
| |
firstFrameImage object (Obrigatório)Uma referência de imagem reutilizada diretamente como o primeiro quadro do World. url e base64 são mutuamente exclusivos (escolha um). Restrições de imagem:
Propriedades url string (Condicionalmente obrigatório)URL da imagem do primeiro quadro. Restrições:
string (Condicionalmente obrigatório)Base64 da imagem do primeiro quadro. Restrições:
string (Opcional)Tipo de imagem de referência. O padrão é default. | |
scriptList object (Obrigatório)Roteiro estruturado. Deve incluir synopsis e um acts não vazio.
Propriedades synopsis string (Obrigatório)Sinopse da história. Não vazia, até 2000 caracteres.videoTitle string (Opcional)Nome do mundo. O padrão é New World, até 128 caracteres.scene string (Opcional)Configuração da cena. O padrão é Static Shot, até 64 caracteres.style string (Opcional)Estilo visual. O padrão é Stable, até 64 caracteres.speed string (Opcional)Ritmo narrativo. O padrão é Steady, até 64 caracteres.language string (Opcional)Idioma do roteiro. O padrão é en (inglês); passe zh para chinês. Até 64 caracteres.setting string (Opcional)Cosmovisão ou cenário de fundo. Até 2000 caracteres.soundtrack string (Opcional)Descrição da trilha sonora. Até 500 caracteres.prologue string (Opcional)Prólogo de abertura. Até 1000 caracteres.videoTags array<string> (Opcional)Tags de vídeo. Até 20 tags, cada uma com até 32 caracteres.subjects array<object> (Opcional)Assuntos predefinidos, até 6. Cada item do array contém as seguintes propriedades:
Propriedades de subjects[] label string (Opcional)Referencia um assunto em acts[].content. Formatado como [character_x], atribuído na ordem do array por padrão.name string (Opcional)Nome legível por humanos, não renderizado como texto na tela. Até 64 caracteres.type string (Opcional)Tipo de assunto. O padrão é character. Determina a aparência do assunto e como as outras propriedades são preenchidas. Valores permitidos:
object (Opcional)Imagem de referência do assunto; url e base64 são mutuamente exclusivos (escolha um), e a imagem deve ser estritamente menor que 6 MB.
Propriedades de refImage url string (Condicionalmente obrigatório)URL da imagem de referência do sujeito.base64 string (Condicionalmente obrigatório)Base64 da imagem de referência do sujeito.referenceType string (Opcional)Tipo de imagem de referência. O padrão é default.string (Opcional)Descrição de gênero. Até 64 caracteres.position string (Opcional)Posição na tela. Até 64 caracteres.ethnicity string (Opcional)Descrição de etnia ou raça. Até 64 caracteres.age string (Opcional)Descrição da idade. Até 64 caracteres.appearance string (Opcional)Detalhes da aparência. Até 500 caracteres.voice string (Opcional)Descrição de voz, taxa de fala e volume. Até 200 caracteres.array<object> (Obrigatório)Roteiro beat a beat, 1–45 entradas, com todo o content totalizando não mais que 100000 caracteres. Cada item do array contém as seguintes propriedades:
Propriedades de acts[] turn int (Opcional)Número da vez. 1–45, sem duplicatas, incrementando a partir de 1 na ordem do array por padrão.content string (Obrigatório)Roteiro para este beat. Não vazio, até 2000 caracteres por beat; pode referenciar assuntos com [character_x].cameraType string (Opcional)Tipo de câmera (como a câmera filma). O padrão é Static. Valores permitidos:
string (Opcional)Tamanho do plano. O padrão é Medium. Determina quanto detalhe este beat pode carregar; altere o tamanho do plano através de cortes e não descreva tanto o corpo inteiro quanto as pontas dos dedos no mesmo beat. Valores permitidos:
cut-in para Close-up, depois cut-out de volta para um plano aberto; use long-take para a maioria dos beats para manter o mesmo tamanho de plano e evitar alternar tamanhos de plano repetidamente.cut string (Opcional)Método de corte (como este beat entra em cena). O padrão é long-take. Valores permitidos:
|
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. | |
data objectDados da resposta. null em caso de falha.
Propriedades encryptedWorldId stringID do Mundo criptografado, retornado nos modos síncrono e assíncrono. Este valor é usado para consultas subsequentes de status de construção, consultas de detalhes do Mundo e troca de credencial de experiência.status stringStatus atual da criação:
stringURL do primeiro quadro do Mundo; null antes de ser gerado. |
Notas adicionais
- Contagem de caracteres: Os limites de "até N caracteres" neste documento são contados por caractere (caracteres Unicode), independentemente de ser chinês ou inglês — caracteres chineses, letras inglesas, dígitos, espaços e pontuação contam cada um como 1 caractere.
-
Requisitos de envio do ScriptList: Ao criar um Mundo,
actsé limitado a 45 entradas, mas não é obrigado a ter exatamente 45; as 45 entradas completas são necessárias apenas ao chamar update-script durante a Viagem. -
Endpoints de controle da Viagem: Os nomes dos endpoints listados sob
creationModelsão endpoints do lado do servidor que podem ser chamados durante a fase de Viagem após a criação do Mundo, não valores de enumeração para a entrada deste endpoint. Seus significados são os seguintes:instruct: enviar instruções de processo de texto para uma Viagem em andamento; somente modo padrão.pause: pausar a Viagem.resume: retomar a reprodução.rewind: retroceder para um ponto de tempo especificado; requer pausa prévia.end: encerrar a Viagem.update-script: substituir totalmente o roteiro; somente modo de roteiro.
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: consulta os metadados completos da criação e o ScriptList.