HappyOyster-Adventure-Create World API Reference

POST

/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds

curl --location 'https://dashscope-intl.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.",
  "eventStyle": "dramatic",
  "firstFrameImage": {
    "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc6.png",
    "referenceType": "default"
  }
}'

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

Scope

Create an Adventure World. Before calling, confirm the following:

Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
Asynchronous mode is recommended: async=true, the API immediately returns encryptedWorldId; poll Query World Build Status for progress.
This endpoint can only create an Adventure World. You do not need to pass mode; creationModel is always simple, uploadMode is fixed to first_frame.

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

Authorizations

string

header

required

QwenCloud API Key. Only the primary API Key (sk- prefix) is supported. See Get an API Key.

Header Parameters

string

default"application/json"

required

Request content type. This parameter must be set to application/json.

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.

Body

application/json

enum<string>

required

Perspective. Omitting this field returns 400000.

Available options:first_person,third_person

string

required

World theme description; Chinese and English are supported. Non-empty, up to 2000 characters. Missing, blank, or over-length returns 400000.

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; strictly less than 6 MB per image; aspect ratio must be landscape, width/height of 1.5-2.0; failing content-safety or copyright/IP verification returns 403004/403005.

Show child attributes

string

First-frame image URL. Mutually exclusive with base64 (choose one). 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.

string

First-frame image base64. Mutually exclusive with url (choose one). 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.

string

default"default"

Reference-image type. Defaults to default, and is currently used as default.

boolean

defaulttrue

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.

enum<string>

default"simple"

Creation sub-mode. Defaults to simple; Adventure supports only simple.

Available options:simple

enum<string>

default"first_frame"

Image upload mode. Defaults to first_frame; Adventure supports only first_frame.

Available options:first_frame

enum<string>

default"normal"

Event style, used to select the script-generation template. Defaults to normal. normal: regular / standard style (default). Completes 4-5 acts per the user's intent at a relatively steady pace, without forcing conflict, reversals, or a three-act climax. dramatic: dramatic / conflict style. Generates a script on a roughly 180-second three-act skeleton: opening hook, rising conflict, turning point, climactic resolution; for open-ended performance it arranges reversals by genre (mystery / thriller / comeback, etc.), with a denser pace and stronger drama. regular: legacy value, equivalent to normal. Kept only for backward compatibility with historical inputs; the server parses it as normal with identical behavior. Do not use it in new calls.

Available options:normal,dramatic,regular

string

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.

Response

200-application/json

integer

Return code. 0 means success; non-zero is an error code.

string

Error message. null on success.

object

Response data. null on failure.

Show child attributes

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.

enum<string>

Current creation status: generating (building) or ready; may also be failed when a synchronous build fails.

Available options:generating,ready,failed

string

World first-frame URL; null before it is generated.

​Scope

Authorizations

Header Parameters

Body

Response

Scope