HappyOyster-Directing-Query World Detail API Reference - Alibaba Cloud Model Studio

Query the current status, creation parameters, and returnable ScriptList information of a single Directing World. For build-progress polling, use the Query World Build Status endpoint.

Scope

Query the current status, creation parameters, and returnable ScriptList information of a single Directing World. Before calling, confirm the following:

Authentication: Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
- Get the primary API Key: Get and configure an API Key.
Prerequisites: Query with the encryptedWorldId returned by Create World. For build-progress polling, use Query World Build Status.
Caller: Called by your server.

HTTP request

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail

Replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters	Query World detail `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` (Required) API Key authentication. Only the primary API Key is supported; it starts with `sk-`, e.g. `sk-xxx`. It is typically configured as the environment variable `$DASHSCOPE_API_KEY`. A temporary API Key (starting with `st-`) returns `403003`.
Query parameters
encryptedWorldId `string` (Required) A Directing encrypted World ID under the current primary account. Returned by Create World.

Response parameters

Query succeeded (script mode)

{
    "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 integer

Return code. 0 means success; non-zero is an error code.

message string

Error message. null on success.

data object

Response data. null on failure.

Properties

encryptedWorldId string

Encrypted World ID.

name string

World name.

status string

Build status: generating / ready / failed.

mode integer

Always 2 for Directing.

creationModel string

simple / scriptlist; determines which control endpoints the Travel can call.

prompt string

The Prompt used when creating in simple mode; fixed to null for scriptlist.

eventStyle string

The event style at creation: normal / dramatic / regular.

perspective null

Usually null for the Directing model.

uploadMode null

Usually null for a Directing World.

resolution string

480p / 720p.

layout string

The camera-movement style for simple mode; usually null when not passed or for scriptlist.

narrative string

The narrative style for simple mode; usually null when not passed or for scriptlist.

refWorldId string

The encrypted reference World ID used for a derived creation.

firstFrameImage object

The first-frame image at creation; base64 is not returned in the response.

inputImages array

The reference images persisted when creating in simple mode; scriptlist does not accept this field, so it is usually null.

scriptList object

Has a value only for a scriptlist World; null when parsing the structured script fails. Contains synopsis, videoTitle, scene, style, speed, language, setting, soundtrack, prologue, videoTags, subjects (with label/name/type/refImage, etc.), and acts (returned in full according to the stored content, with turn/content/cameraType/shotSize/cut).

previewUrl null

Currently fixed to null.

aspectRatio null

Fixed to null for the Directing model.

createdAt string

Creation time, in ISO 8601 format.

updatedAt string

Last update time, in ISO 8601 format.

Prerequisite states and call notes

This endpoint can query a generating, ready, or failed World.
It does not echo the async field from the creation request.
Image fields return only URL and referenceType, and never return base64. The inputImages for simple mode are persisted as reference images and can be returned in the detail; scriptlist does not accept this field.
When scriptList parses normally, the full stored structure is returned, and acts is returned in full according to the stored content; when parsing fails, scriptList=null is returned, and an empty acts is not used to indicate a parsing failure.
Querying a World from another model, another primary account, or one that has been deleted all return 403001, without revealing whether the resource exists.

Error codes

If the model call fails and returns an error, see HappyOyster Error Codes to resolve it.

Next steps

Query World List: paginate through all Directing Worlds.
Delete World: delete a World you no longer use.
When the World is ready, you can Get Travel Credential.