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

Query the full metadata and echoable creation parameters of a single Acting World. For build-progress polling, use the Query World Build Status endpoint.

Scope

Query the full metadata and echoable creation parameters of a single Acting 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-acting/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-acting/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-acting/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) An Acting encrypted World ID under the current primary account. Returned by Create World.

Response parameters

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "Late-Night Video Call",
        "status": "ready",
        "mode": 3,
        "creationModel": "simple",
        "prompt": "During a late-night video call, a quiet girl smiles back at the camera",
        "eventStyle": "first_frame",
        "perspective": null,
        "uploadMode": "first_frame",
        "resolution": "480p",
        "aspectRatio": "9:16",
        "layout": null,
        "narrative": null,
        "refWorldId": null,
        "firstFrameImage": {
            "url": "https://cdn.happyoyster.com/frames/portrait-call.jpg",
            "referenceType": "default"
        },
        "inputImages": null,
        "sceneImage": null,
        "roleImage": null,
        "scenePrompt": null,
        "rolePrompt": null,
        "scriptList": null,
        "previewUrl": null,
        "createdAt": "2026-09-09T08:00:00Z",
        "updatedAt": "2026-09-09T08: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 3 for Acting.

creationModel string

Always simple for Acting.

prompt string

The top-level prompt submitted at creation.

eventStyle string

A compatibility return field; when a compliant creation omits this field, the server usually maps it from uploadMode and echoes first_frame. It is not an Acting creation parameter, and clients should not send it back.

perspective null

Acting does not accept a perspective creation parameter; fixed to null.

uploadMode string

Fixed to first_frame.

resolution string

480p / 720p; 480p if not passed at creation.

aspectRatio string

9:16 / 16:9; 9:16 if not passed at creation.

layout null

Acting does not accept this creation parameter; fixed to null.

narrative null

Acting does not accept this creation parameter; fixed to null.

refWorldId string

The Acting encrypted reference World ID used for a derived creation; null if none.

firstFrameImage object

The required first-frame image at creation; returned in URL form only, base64 is not returned. Contains url and referenceType.

inputImages null

Acting does not currently use this field.

sceneImage null

Acting does not use the scene/role image slots; fixed to null.

roleImage null

Acting does not use the scene/role image slots; fixed to null.

scenePrompt null

Acting does not use scene/role prompts; fixed to null.

rolePrompt null

Acting does not use scene/role prompts; fixed to null.

scriptList null

Acting does not support ScriptList; fixed to null.

previewUrl null

Currently fixed to null.

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; some build artifacts may be null before they are ready.
The detail endpoint does not echo async, because it is a call-behavior switch, not a World attribute.
Images are returned only as URL and referenceType; the base64 content in the creation request is not returned.
eventStyle usually has the same value as uploadMode; clients should treat uploadMode as the authoritative field for the Acting creation mode.
The player can pre-read aspectRatio, but when actually entering the room it should still set the orientation from the Enter Travel response value.
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 Acting Worlds.
Delete World: delete a World you no longer use.
When the World is ready, you can Get Travel Credential.