All Products
Search

This Product

    Alibaba Cloud Model Studio:HappyOyster-Adventure-Query World Build Status API Reference

    Document Center

    Alibaba Cloud Model Studio:HappyOyster-Adventure-Query World Build Status API Reference

    Last Updated:Sep 20, 2026

    Query the build progress of an Adventure World. The API returns the encrypted World ID, build status, and first-frame URL; the client polls until the World enters ready.

    Scope

    Query the build progress of an Adventure World. Before calling, confirm the following:

    • Authentication: The primary API Key is not required; either the primary or a temporary API Key can call this endpoint. For how to obtain them, see Obtain authentication credentials.
    • Prerequisites: Query with the encryptedWorldId returned by Create World. You can start querying from the generating state.
    • Caller: Either your server or your client can call it.

    HTTP request

    Singapore

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

    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/build-status

    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/build-status

    Replace {WorkspaceId} with your actual Workspace ID.

    Request parameters

    Query World build status

    curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/build-status?encryptedWorldId={encryptedWorldId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"

    Authorization string (Required)

    API Key authentication. The primary API Key is not required; either the primary or a temporary API Key can call it.

    • Primary API Key: starts with sk-, e.g. sk-xxx.
    • Temporary API Key: starts with st-, e.g. st-xxx.
    Query parameters

    encryptedWorldId string (Required)

    The encrypted World ID returned by Create World. It is encrypted by the server; you do not need to decrypt it.

    Response parameters

    Building

    {
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}

    Build complete

    {
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "ready",
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "name": "Cyberpunk Detective World",
        "mode": 1
    }
}

    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.

    status string

    Build status:

    • generating: building
    • ready: ready; you can exchange for a travel credential and enter the room
    • failed: build failed

    firstFrame string

    World first-frame URL; null when not yet generated or when the build failed.

    name string

    World name. Returned only when status=ready.

    mode integer

    Always 1 for Adventure. Returned only when status=ready.

    Prerequisite states and call notes

    • Poll every 3–5 seconds until status is ready or failed.
    • Only a ready World can exchange for a travel credential and enter the room.
    • When a URL image fails validation after asynchronous storage, the World may go from generating to failed.
    • This endpoint does not return aspectRatio; when you need creation metadata such as perspective or uploadMode, call Query World Detail.

    Error codes

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

    Next steps

    After the World enters ready: