Skip to main content

Referência da API HappyOyster-Acting-Create World

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

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

  • 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-acting/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "prompt": "A blonde girl with twin tails, a white bow, and a golden crescent crown on her forehead; a white shirt with a navy sailor collar and a blue bow tie, and a blue-and-white argyle short skirt. Her right hand holds up a yellow sticky note that reads \"Good night\". Behind her are a deep-red velvet curtain and a cluster of flowers. Facing the camera, an anime-realistic blend, warm indoor lighting.",
    "resolution": "480p",
    "aspectRatio": "9:16",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc5.png",
        "referenceType": "default"
    }
}'
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. 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:
  • 480p
  • 720p
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 (retrato): recomenda-se um primeiro quadro em retrato
  • 16:9 (paisagem): recomenda-se um primeiro quadro em paisagem
Ou seja, para streaming em retrato (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:
  • Formato: JPG / JPEG / PNG / WebP
  • Tamanho: estritamente menor que 6 MB por imagem
  • Proporção: quando aspectRatio=9:16, largura / altura é 0.5–0.667; quando aspectRatio=16:9, é 1.5–2.0
  • 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 referência do primeiro quadro. O padrão é default, e atualmente é usado como default.

Parâmetros de resposta

  • Criação assíncrona
  • Falha na solicitação
{
    "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; 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:
  • generating: construindo
  • ready: pronto
  • failed: falha na construção
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: