HappyOyster-Adventure-Query World List API Reference - Alibaba Cloud Model Studio

Paginate through the Adventure Worlds under the current primary account. The endpoint is automatically isolated by model and never returns Directing or Acting Worlds.

Scope

Paginate through the Adventure Worlds under the current primary account. 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.
Caller: Called by your server.

HTTP request

Singapore

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

Replace {WorkspaceId} with your actual Workspace ID.

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds

Replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

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

Replace {WorkspaceId} with your actual Workspace ID.

Request parameters

Query World list

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds?page=1&pageSize=20&status=ready' \
    -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

page integer (Optional)

Page number, defaults to 1. When page <= 0 it is treated as 1.

pageSize integer (Optional)

Items per page, defaults to 20. When pageSize <= 0 it is treated as 20; when greater than 100 it is capped at 100.

status string (Optional)

Filter by build status. Unknown values are not applied as a filter. Allowed values:

generating: building
ready: ready
failed: build failed

mode integer (Optional)

No need to pass this. The list is already filtered to the Adventure model, and items[].mode is always 1. If you still pass it and the value is not 1, 400000 is returned.

Response parameters

Query succeeded

{
    "code": 0,
    "message": null,
    "data": {
        "items": [
            {
                "encryptedWorldId": "enc_a1b2****",
                "name": "Cyberpunk Detective World",
                "status": "ready",
                "mode": 1,
                "previewUrl": null,
                "createdAt": "2026-06-03T10:00:00Z",
                "perspective": "first_person",
                "creationModel": "simple",
                "uploadMode": "first_frame"
            }
        ],
        "pagination": {
            "page": 1,
            "pageSize": 20,
            "total": 1,
            "hasMore": false
        }
    }
}

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

items array

The Worlds on the current page; an empty array when there is no result. Each item contains encryptedWorldId, name, status (generating / ready / failed), mode (always 1), previewUrl (usually null), createdAt, perspective (first_person / third_person), creationModel (always simple), and uploadMode (fixed to first_frame).

pagination object

Pagination info. Contains page, pageSize, total, and hasMore (true when page × pageSize < total).

Prerequisite states and call notes

List items are lightweight snapshots; they do not return images, prompts, refWorldId, or other full creation parameters. When you need the full configuration, call Query World Detail.
An unknown status does not raise an error; it is treated as no status filter.
When paging, use pagination.pageSize and hasMore from the response; do not assume the requested values are adopted verbatim.
An empty result is not an error; it returns items=[] and the corresponding pagination info.

Error codes

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

Next steps

Query World Detail: view the full metadata of a single World.
Delete World: delete a World you no longer use.