Skip to main content

Referência da API HappyOyster-Directing-Query World Detail

Consulte o status atual, os parâmetros de criação e as informações retornáveis do ScriptList de um único Mundo do Directing. Para polling de progresso de construção, use o endpoint Query World Build Status.

Escopo

Consulte o status atual, os parâmetros de criação e as informações retornáveis do ScriptList de um único Mundo do Directing. Antes de chamar, confirme o seguinte:

Solicitação HTTP

  • Singapore
  • EUA (Virgínia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detailSubstitua {WorkspaceId} pelo seu ID do Workspace real.

Parâmetros da solicitação

  • Consultar detalhes do Mundo
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
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.
Parâmetros de consulta
encryptedWorldId string (Obrigatório)Um ID de Mundo criptografado do Directing na conta principal atual. Retornado por Criar Mundo.

Parâmetros de resposta

  • Consulta bem-sucedida (modo script)
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "Midnight Visitor",
        "status": "ready",
        "mode": 2,
        "creationModel": "scriptlist",
        "prompt": null,
        "eventStyle": "normal",
        "perspective": null,
        "uploadMode": null,
        "resolution": "720p",
        "layout": null,
        "narrative": null,
        "refWorldId": null,
        "firstFrameImage": {
            "url": "https://cdn.happyoyster.com/frames/room.png",
            "referenceType": "default"
        },
        "inputImages": null,
        "scriptList": {
            "synopsis": "Late at night, Su Li is startled awake by a knock at the door.",
            "videoTitle": "Midnight Visitor",
            "subjects": [
                {
                    "label": "[character_1]",
                    "name": "Su Li",
                    "type": "character",
                    "refImage": {
                        "url": "https://cdn.happyoyster.com/subjects/suli.png",
                        "referenceType": "default"
                    }
                }
            ],
            "acts": [
                {
                    "turn": 1,
                    "content": "Rain beats against the window, and [character_1] is startled awake from sleep.",
                    "cameraType": "Static",
                    "shotSize": "Wide",
                    "cut": "long-take"
                },
                {
                    "turn": 2,
                    "content": "[character_1] walks toward the door, and the knocking sounds again outside.",
                    "cameraType": "Push-in",
                    "shotSize": "Close-up",
                    "cut": "long-take"
                }
            ]
        },
        "previewUrl": null,
        "aspectRatio": null,
        "createdAt": "2026-06-03T10:00:00Z",
        "updatedAt": "2026-06-03T10:05:00Z"
    }
}
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.name stringNome do Mundo.status stringStatus da construção: generating / ready / failed.mode integerSempre 2 para Direção.creationModel stringsimple / scriptlist; determina quais endpoints de controle a Viagem pode chamar.prompt stringO Prompt usado ao criar no modo simple; fixo como null para scriptlist.eventStyle stringO estilo de evento na criação: normal / dramatic / regular.perspective nullGeralmente null para o modelo Directing.uploadMode nullGeralmente null para um Mundo do Directing.resolution string480p / 720p.layout stringO estilo de movimento de câmera para o modo simple; geralmente null quando não passado ou para scriptlist.narrative stringO estilo narrativo para o modo simple; geralmente null quando não passado ou para scriptlist.refWorldId stringO ID de Mundo de referência criptografado usado para uma criação derivada.firstFrameImage objectA imagem do primeiro quadro na criação; base64 não é retornado na resposta.inputImages arrayAs imagens de referência persistidas ao criar no modo simple; scriptlist não aceita este campo, portanto, geralmente é null.scriptList objectTem valor apenas para um Mundo scriptlist; null quando a análise do script estruturado falha. Contém synopsis, videoTitle, scene, style, speed, language, setting, soundtrack, prologue, videoTags, subjects (com label/name/type/refImage, etc.) e acts (retornado integralmente de acordo com o conteúdo armazenado, com turn/content/cameraType/shotSize/cut).previewUrl nullAtualmente fixado em null.aspectRatio nullFixado como null para o modelo de Direção.createdAt stringHora de criação, no formato ISO 8601.updatedAt stringÚltima hora de atualização, no formato ISO 8601.

Estados pré-requisitos e notas de chamada

  • Este endpoint pode consultar um Mundo generating, ready ou failed.
  • Ele não ecoa o campo async da solicitação de criação.
  • Os campos de imagem retornam apenas URL e referenceType, e nunca retornam base64. Os inputImages para o modo simple são persistidos como imagens de referência e podem ser retornados nos detalhes; scriptlist não aceita este campo.
  • Quando scriptList é analisado normalmente, a estrutura completa armazenada é retornada, e acts é retornado integralmente de acordo com o conteúdo armazenado; quando a análise falha, scriptList=null é retornado, e um acts vazio não é usado para indicar uma falha de análise.
  • Consultar um Mundo de outro modelo, de outra conta principal ou que tenha sido excluído retorna 403001, sem revelar se o recurso existe.

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