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

Query the build progress of an Acting 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 Acting 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; the World does not need to be fully built.
• Caller: Either your server or your client can call it.

HTTP request

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

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

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "ready",
        "firstFrame": "https://cdn.happyoyster.com/frames/acting_world_xyz789.jpg",
        "name": "Late-Night Video Call",
        "mode": 3
    }
}

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; the player orientation is determined by the aspectRatio in the Enter the room response.

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:

• Get Travel Credential: exchange for a single-use ticket.
• Query World Detail: query the full creation metadata.