Skip to main content

Referência da API HappyOyster-Adventure-Create World

Crie um World de exploração mundial. Crie um World a partir de um prompt em linguagem natural e uma imagem de primeiro quadro obrigatória; a API retorna imediatamente um ID criptografado do World, o World é construído de forma assíncrona em segundo plano e o cliente consulta o progresso da construção até sua conclusão.

Escopo

Crie um Adventure World. 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 Adventure World. Você não precisa passar mode (o servidor grava 1; passar um valor diferente de 1 retorna 400000). creationModel é sempre simple, uploadMode é fixo em first_frame e a versão de entrada na sala é fixa em wanderV2.

Solicitação HTTP

  • Singapore
  • China (Pequim)
  • EUA (Virgínia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worldsSubstitua {WorkspaceId} pelo seu ID do Workspace real.

Parâmetros da solicitação

  • Imagem do primeiro quadro (assíncrono)
  • Base64 da imagem do primeiro quadro (assíncrono)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "perspective": "third_person",
    "prompt": "Third-person tracking shot: a rider in a black snowsuit and black helmet drives a black snowmobile into the distance, the track kicking up fine snow. Ahead lies a snow-covered coniferous forest; farther off, steep sunlit rock cliffs of snow mountains under a blue sky with white clouds. Clear winter sky, strong snow highlights, open and crisp.",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png"
    }
}'
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.
perspective string (Obrigatório)Perspectiva. Valores permitidos:
  • first_person: primeira pessoa
  • third_person: terceira pessoa
A omissão deste campo retorna 400000.
prompt string (Obrigatório)Descrição do tema do World; chinês e inglês são suportados. Não vazio, até 2000 caracteres. Ausente, em branco ou excedendo o limite retorna 400000.
creationModel string (Opcional)Submodo de criação. O padrão é simple; Adventure suporta apenas simple.
uploadMode string (Opcional)Modo de upload de imagem. O padrão é first_frame; Adventure suporta apenas first_frame.
refWorldId string (Opcional)Derive uma nova criação de um Adventure World existente. Deve ser um ID criptografado de Adventure World sob a conta principal atual; um World de outro modelo ou de outra conta principal retorna 403001.
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. Mutuamente exclusivo com base64 (escolha um). 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. Mutuamente exclusivo com url (escolha um). 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 e atualmente é usado como default.

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 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: generating (construindo) ou ready; também pode ser failed quando uma construção síncrona falha.firstFrame 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: