HappyOyster-Adventure-Create World API Reference

​

Scope

• 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.
• Call mode: Asynchronous mode is recommended.
  • Asynchronous mode (default): async=true, the API immediately returns encryptedWorldId; poll Query World Build Status for progress.
  • Synchronous mode: async=false, the server polls internally (every 3s, up to 120s) and returns when the build completes; on timeout it falls back to asynchronous and the client keeps polling.
• Endpoint restrictions: This endpoint can only create an Adventure World. You do not need to pass mode (the server writes 1; passing a value other than 1 returns 400000). creationModel is always simple, uploadMode is fixed to first_frame, and the enter-room version is fixed to wanderV2.

​

HTTP request

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "perspective": "third_person",
    "prompt": "Third-person tracking shot: a rider in a black snowsuit and black helmet drives a black snowmobile into the distance, the track kicking up fine snow. Ahead lies a snow-covered coniferous forest; farther off, steep sunlit rock cliffs of snow mountains under a blue sky with white clouds. Clear winter sky, strong snow highlights, open and crisp.",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png"
    }
}'

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "perspective": "third_person",
    "prompt": "Third-person tracking shot: a rider in a black snowsuit and black helmet drives a black snowmobile into the distance, the track kicking up fine snow. Ahead lies a snow-covered coniferous forest; farther off, steep sunlit rock cliffs of snow mountains under a blue sky with white clouds. Clear winter sky, strong snow highlights, open and crisp.",
    "firstFrameImage": {
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    }
}'

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

​

Error codes

​

Next steps

• Query World Build Status: poll every 3–5 seconds until the World enters ready.
• After the World enters ready, call Get Travel Credential to exchange for a single-use ticket.
• Query World Detail: query the full creation metadata.