Create a world exploration World. Create a World from a natural-language prompt and a required first-frame image; the API immediately returns an encrypted World ID, the World builds asynchronously in the background, and the client polls the build progress until it completes.
Scope
Create an Adventure World. Before calling, confirm the following:
-
Authentication: Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
-
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
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
Replace {WorkspaceId} with your actual Workspace ID.
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
Replace {WorkspaceId} with your actual Workspace ID.
US (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds
Replace {WorkspaceId} with your actual Workspace ID.
Request parameters | First-frame image (async)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"
}
}'
First-frame image base64 (async)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..."
}
}'
|
Content-Typestring(Required) Request content type. This parameter must be set to application/json. |
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. |
Request Body |
async boolean (Optional) Whether to create asynchronously. Defaults to true:
true: returns immediately; the World builds in the background, and the client polls Query World Build Status.false: the server polls every 3 seconds for up to 120 seconds and returns when the build completes; on timeout it still returns generating, and the client then polls on its own. |
perspective string (Required) Perspective. Allowed values:
first_person: first personthird_person: third person Omitting this field returns 400000. |
prompt string (Required) World theme description; Chinese and English are supported. Non-empty, up to 2000 characters. Missing, blank, or over-length returns 400000. |
creationModel string (Optional) Creation sub-mode. Defaults to simple; Adventure supports only simple. |
uploadMode string (Optional) Image upload mode. Defaults to first_frame; Adventure supports only first_frame. |
refWorldId string (Optional) Derive a new creation from an existing Adventure World. Must be an Adventure encrypted World ID under the current primary account; a World from another model or another primary account returns 403001. |
firstFrameImage object (Required) An image reference reused directly as the World's first frame. url and base64 are mutually exclusive (choose one). Image constraints:
- Format: JPG / JPEG / PNG / WebP
- Size: strictly less than 6 MB per image
- Aspect ratio: must be landscape, width / height of 1.5–2.0 (the frame ratio follows this image)
- Content safety: failing content-safety or copyright / IP verification returns
403004 / 403005
Properties url string (Conditionally required) First-frame image URL. Mutually exclusive with base64 (choose one). Constraints:
- Must be a valid
http / https URL with a host, accessible by the server
- The actual format, size, and first-frame aspect ratio are validated after storage
- An async request may first return
generating, then the World enters failed due to image validation failure
base64 string (Conditionally required) First-frame image base64. Mutually exclusive with url (choose one). Constraints:
- A complete data URI
data:image/<subtype>;base64,<payload> is recommended
- Format, size, and first-frame aspect ratio are validated synchronously at the creation entry point
referenceType string (Optional) Reference-image type. Defaults to default, and is currently used as default. |
Response parameters | Async create{
"code": 0,
"message": null,
"data": {
"encryptedWorldId": "enc_a1b2****",
"status": "generating",
"firstFrame": null
}
}
|
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 The encrypted World ID generated by the server. Returned in both synchronous and asynchronous modes; used for subsequent build-status polling, detail queries, and exchanging a travel credential. status string Current creation status: generating (building) or ready; may also be failed when a synchronous build fails. firstFrame string World first-frame URL; null before it is generated. |
Error codes
If the model call fails and returns an error, see HappyOyster Error Codes to resolve it.
Next steps
After creating successfully, you can: