Skip to main content
Directing Open API Reference

HappyOyster-Directing-Query World Build Status API Reference

Query the build progress of a Directing 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 a Directing 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
  • US (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/build-statusReplace {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-directing/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 Directing encrypted World ID returned by Create World.

Response parameters

  • Building
  • Build complete
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}
code integerReturn code. 0 means success; non-zero is an error code.
message stringError message. null on success.
data objectResponse data. null on failure.

Properties

encryptedWorldId stringEncrypted World ID.status stringBuild status: generating / ready / failed.firstFrame stringWorld first-frame URL; null when not yet generated or when the build failed.name stringWorld name. Returned only when status=ready.mode integerAlways 2 for Directing. 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.

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:
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More