Skip to main content

Referência da API HappyOyster-Directing-Create World

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).
  • Modo de chamada: Recomenda-se o modo assíncrono.
    • Modo assíncrono (padrão): async=true, a API retorna imediatamente encryptedWorldId; 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.
  • Restrições do endpoint: Este endpoint só pode criar um Mundo de Direção. Você não precisa passar mode (o servidor grava 2; passar um valor diferente de 2 retorna 400000). creationModel suporta simple (modo padrão, padrão) e scriptlist (modo de roteiro); a versão de entrada na sala é fixa em storyV2, e aspectRatio e maxExperienceTimeSec são fixos em null.

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

  • Modo padrão · texto simples (criação assíncrona)
  • Modo padrão · texto + imagem de referência (criação assíncrona)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "First-person (POV) interactive video: the camera simulates my own eyes, locked on a white Maltese puppy directly in front of me — white chef's hat, black-buttoned chef's coat. Soft home-kitchen background, warm light, the puppy's gaze always facing the camera.",
    "resolution": "720p",
    "layout": "Stable",
    "narrative": "Calm"
}'
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:
  • true: retorna imediatamente; o Mundo é construído em segundo plano, e o cliente consulta Consultar Status de Construção do Mundo.
  • false: o servidor consulta a cada 3 segundos por até 120 segundos e retorna quando a construção for concluída; em caso de tempo limite, ainda retorna generating, e o cliente passa a consultar por conta própria.
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:
  • instruct: enviar instruções de processo de texto
  • pause: pausar
  • resume: retomar
  • rewind: retroceder
  • end: terminar
Consulte Notas adicionais para obter uma descrição de cada endpoint.
eventStyle string (Opcional)Aplica-se apenas a creationModel=simple: seleciona o modelo de geração de roteiro. O padrão é normal. Valores permitidos:
  • normal: estilo regular / padrão (padrão). Completa 4–5 atos conforme a intenção do usuário em um ritmo relativamente constante, sem forçar conflitos, reviravoltas ou um clímax de três atos.
  • dramatic: estilo dramático / de conflito. Gera um roteiro em um esqueleto de três atos de aproximadamente 180 segundos: gancho inicial, conflito crescente, ponto de virada, resolução climática; para performances abertas, organiza reviravoltas por gênero (mistério / suspense / retorno, etc.), com um ritmo mais denso e drama mais forte.
  • regular: valor legado, mantido apenas para compatibilidade retroativa com entradas históricas; o servidor o analisa como normal. Não use em novas chamadas.
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:
  • 480p
  • 720p
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:
  • Stable: câmera estável, pouco movimento, favorecendo planos-sequência contínuos com cortes esparsos
  • Fast: câmera rápida, forte impulso, com cortes secos mais densos / zooms rápidos / saltos de tamanho de plano
  • Calm: entre os dois, uma câmera contida que não é nem apressada nem agressiva
narrative string (Opcional)Estilo narrativo (quão denso é o drama e quão forte é a emoção). Valores permitidos:
  • Calm: poucos eventos, favorecendo a atmosfera e uma progressão lenta
  • Dramatic: eventos densos, com reações / reviravoltas / obstáculos mais pronunciados e alta tensão
  • Normal: densidade narrativa regular, um nível intermediário
  • Steady: ritmo uniforme sem acumular clímaxes, próximo de Normal
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:
  • Formato: JPG / JPEG / PNG / WebP
  • Tamanho: estritamente menor que 6 MB por imagem
  • Proporção: deve ser paisagem, largura / altura de 1.5–2.0 (a proporção do quadro segue esta imagem)
  • Segurança de conteúdo: falha na verificação de segurança de conteúdo ou direitos autorais / IP retorna 403004 / 403005

Propriedades

url string (Condicionalmente obrigatório)URL da imagem do primeiro quadro. Restrições:
  • Deve ser uma URL http / https válida com um host, acessível pelo servidor
  • O formato real, o tamanho e a proporção do primeiro quadro são validados após o armazenamento
  • Uma solicitação assíncrona pode retornar primeiro generating, depois o Mundo entra em failed devido a falha na validação da imagem
base64 string (Condicionalmente obrigatório)Base64 da imagem do primeiro quadro. Restrições:
  • Recomenda-se um URI de dados completo data:image/<subtype>;base64,<payload>
  • Formato, tamanho e proporção do primeiro quadro são validados sincronamente no ponto de entrada da criação
referenceType 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:
  • Formato: JPG / JPEG / PNG / WebP
  • Tamanho: estritamente menor que 6 MB por imagem
  • Proporção: deve ser paisagem, largura / altura de 1.5–2.0 (a proporção do quadro segue esta imagem)
  • Segurança de conteúdo: falha na verificação de segurança de conteúdo ou direitos autorais / IP retorna 403004 / 403005

Propriedades

url string (Condicionalmente obrigatório)URL da imagem. Restrições:
  • Deve ser uma URL http / https válida com um host, acessível pelo servidor
  • O formato, tamanho e proporção reais são validados após o armazenamento
  • Uma solicitação assíncrona pode retornar primeiro generating, depois o Mundo entra em failed devido a falha na validação da imagem
base64 string (Condicionalmente obrigatório)Base64 da imagem. Restrições:
  • Recomenda-se um URI de dados completo data:image/<subtype>;base64,<payload>
  • Formato, tamanho e proporção são validados sincronizadamente no ponto de entrada da criação
referenceType string (Opcional)Tipo de imagem de referência. O padrão é default.

Modo de roteiro (creationModel=scriptlist)

Parâmetros da solicitação

  • Modo de script (criação assíncrona)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "scriptlist",
    "resolution": "720p",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
        "referenceType": "default"
    },
    "scriptList": {
        "videoTitle": "Su Nian · Sitting with You for a While Tonight",
        "synopsis": "The young girl Su Nian sits at a light-colored desk facing the camera, chatting with you slowly and helping you let go of the day.",
        "subjects": [
            {
                "label": "[character_1]",
                "name": "Su Nian",
                "type": "character",
                "gender": "female",
                "age": "young girl",
                "ethnicity": "East Asian",
                "appearance": "medium-length straight black hair with a side part, a rounded face, a cream-white knit top, anime style, clean lines",
                "position": "center of the frame, seated at a light-colored desk",
                "voice": "gentle girlish voice, slightly slow pace, moderate volume"
            }
        ],
        "acts": [
            {
                "turn": 1,
                "content": "[character_1] sits at the light-colored desk facing the camera, leaning slightly forward, eyes curving as she softly says, \"Hey, I'll sit with you for a while again tonight, let's chat slowly.\"",
                "cameraType": "Push-in",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] folds her hands on the desk, nods gently, and says, \"Let's set aside all the worries of the day for now.\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 3,
                "content": "[character_1] tilts her head slightly, looking at the camera with a gentle expression, and asks, \"How was your day? Are you okay, are you tired?\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            }
        ]
    }
}'
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:
  • true: retorna imediatamente; o Mundo é construído em segundo plano, e o cliente consulta Consultar Status de Construção do Mundo.
  • false: o servidor consulta a cada 3 segundos por até 120 segundos e retorna quando a construção for concluída; em caso de tempo limite, ainda retorna generating, e o cliente passa a consultar por conta própria.
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:
  • update-script: substituir totalmente o roteiro
  • pause: pausar
  • resume: retomar
  • rewind: retroceder
  • end: terminar
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:
  • 480p
  • 720p
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:
  • Formato: JPG / JPEG / PNG / WebP
  • Tamanho: estritamente menor que 6 MB por imagem
  • Proporção: deve ser paisagem, largura / altura de 1.5–2.0 (a proporção do quadro segue esta imagem)
  • Segurança de conteúdo: falha na verificação de segurança de conteúdo ou direitos autorais / IP retorna 403004 / 403005

Propriedades

url string (Condicionalmente obrigatório)URL da imagem do primeiro quadro. Restrições:
  • Deve ser uma URL http / https válida com um host, acessível pelo servidor
  • O formato real, o tamanho e a proporção do primeiro quadro são validados após o armazenamento
  • Uma solicitação assíncrona pode retornar primeiro generating, depois o Mundo entra em failed devido a falha na validação da imagem
base64 string (Condicionalmente obrigatório)Base64 da imagem do primeiro quadro. Restrições:
  • Recomenda-se um URI de dados completo data:image/<subtype>;base64,<payload>
  • Formato, tamanho e proporção do primeiro quadro são validados sincronamente no ponto de entrada da criação
referenceType 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:
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:
  • character: personagem humano (padrão). Preencha gender / position / ethnicity / age / appearance como para uma pessoa.
  • animal: animal real (gato, cachorro, cavalo, etc.). Use espécie em vez de gênero e subespécie / raça em vez de etnia.
  • creature: criatura não humana / fantástica (dragão, monstro, alienígena, etc.). Preencha também para uma aparência não humana.
  • narrator: narrador / voz off. Apenas voz, não aparece na tela; preencha voice e nenhuma imagem de referência será gerada.
refImage 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.
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.
gender 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.
acts 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:
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:
  • Static: câmera travada no lugar, sem zoom ou giro (padrão). O tamanho do plano é controlado por shotSize: amplo / médio / fechado
  • Tracking: plano de acompanhamento. A câmera segue o assunto, mantendo a distância de rastreamento
  • Pan Left: câmera parada, panorâmica para a esquerda
  • Pan Right: câmera parada, panorâmica para a direita
  • Tilt Up: câmera inclina para cima
  • Tilt Down: câmera inclina para baixo
  • Push-in: zoom in óptico / físico, o quadro se aproxima gradualmente
  • Pull-out: afastar, o quadro se amplia gradualmente
  • POV Forward: primeira pessoa, a câmera são os olhos, caminhando para frente
  • POV Look Down: primeira pessoa olhando para baixo
  • POV Look Up: primeira pessoa olhando para cima
  • POV Turn Left: primeira pessoa virando para a esquerda para olhar
  • POV Turn Right: primeira pessoa virando para a direita para olhar
shotSize 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:
  • Wide: plano geral / aberto, incluindo o corpo inteiro e sua relação com o ambiente. Adequado para marcação, posicionamento e encenação espacial; não descreva microexpressões ou pontas dos dedos.
  • Medium: plano médio (padrão), postura e gestos da parte superior do corpo. Adequado para diálogos e ações cotidianas; não descreva marcação de pés ou operações finas das mãos.
  • Close-up: close-up, um rosto / uma mão / um adereço. Adequado para expressões e detalhes-chave; não descreva movimentos de corpo inteiro.
Combinando com cortes: para ver mais detalhes, primeiro faça 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:
  • long-take: sem corte, continuando do plano anterior. Padrão e o mais estável
  • hard-cut: corte seco, trocando instantaneamente para outro plano. Use isto para diálogos em plano/contraplano
  • cut-in: corta para um plano mais fechado, ex. Medium → Close-up. Use para visualizar detalhes e cortar para interações manuais
  • cut-out: corta para um plano mais aberto, ex. Close-up → Medium / Wide
  • cutaway: corte breve para um detalhe fora da linha principal
  • cutback: volta ao assunto principal a partir de um cutaway. Só pode seguir um cutaway
  • camera movement transition: conecta dois segmentos com movimento rápido da câmera em vez de um corte seco

Parâmetros de resposta

  • Criação assíncrona
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}
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:
  • generating: construindo
  • ready: pronto
  • failed: falha na construção
firstFrame 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 creationModel sã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:

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: