All Products
Search

This Product

    Alibaba Cloud Model Studio:HappyOyster-Directing-Query World List API Reference

    Document Center

    Alibaba Cloud Model Studio:HappyOyster-Directing-Query World List API Reference

    Last Updated:Sep 20, 2026

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

    Scope

    Paginate through the Directing 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).

    • 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

    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

    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-directing/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 Directing model, and items[].mode is always 2. If you still pass it and the value is not 2, 400000 is returned.

    Response parameters

    Query succeeded

    {
    "code": 0,
    "message": null,
    "data": {
        "items": [
            {
                "encryptedWorldId": "enc_a1b2****",
                "name": "Midnight Visitor",
                "status": "ready",
                "mode": 2,
                "perspective": null,
                "creationModel": "scriptlist",
                "uploadMode": null,
                "createdAt": "2026-06-03T10:00:00Z"
            },
            {
                "encryptedWorldId": "enc_g7h8****",
                "name": "Neon Alley",
                "status": "ready",
                "mode": 2,
                "perspective": null,
                "creationModel": "simple",
                "uploadMode": null,
                "createdAt": "2026-06-03T12:00:00Z"
            }
        ],
        "pagination": {
            "page": 1,
            "pageSize": 20,
            "total": 2,
            "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 2), perspective (usually null), creationModel (simple / scriptlist), uploadMode (usually null), and createdAt.

    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, scriptList, or aspectRatio. When you need the full metadata, call Query World Detail by encryptedWorldId.
    • 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.

    Error codes

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

    Next steps