Skip to main content
QwenCloud home page
Docs
Acting (Invitational Preview)

HappyOyster-Acting-Create World API Reference

Create a role-play World. Create a World from a natural-language prompt and a required first-frame image; the API immediately returns an encrypted World ID (encryptedWorldId), the World builds asynchronously in the background, and the client polls the build progress until it completes.

POST
/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds
curl --location 'https://dashscope-intl.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "async": true,
  "prompt": "A blonde girl with twin tails, a white bow, and a golden crescent crown on her forehead; a white shirt with a navy sailor collar and a blue bow tie, and a blue-and-white argyle short skirt. Her right hand holds up a yellow sticky note that reads \"Good night\". Behind her are a deep-red velvet curtain and a cluster of flowers. Facing the camera, an anime-realistic blend, warm indoor lighting.",
  "resolution": "480p",
  "aspectRatio": "9:16",
  "firstFrameImage": {
    "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc5.png",
    "referenceType": "default"
  }
}'
{
  "code": 0,
  "message": null,
  "data": {
    "encryptedWorldId": "enc_a1b2****",
    "status": "generating",
    "firstFrame": null
  }
}

Scope

Create an Acting 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. async=true immediately returns encryptedWorldId; poll Query World Build Status for progress.
  • Endpoint restrictions: This endpoint can only create an Acting World. You do not need to pass mode (the server writes 3). creationModel is always simple, uploadMode is fixed to first_frame, and the enter-room version is fixed to actingV2.
If the model call fails and returns an error, see HappyOyster Error Codes to resolve it.

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
​
string
required

A natural-language description of the character, scene, and performance goal. Non-empty, up to 2000 characters. Missing, blank, or over-length returns 400000.

​
object
required

An image reference reused 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; the width/height ratio must match aspectRatio (0.5-0.667 for 9:16, 1.5-2.0 for 16:9); failing content-safety or copyright/IP verification returns 403004/403005.

​
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; Acting supports only simple.

Available options:simple
​
enum<string>
default"first_frame"

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

Available options:first_frame
​
enum<string>
default"480p"

Video resolution. Defaults to 480p.

Available options:480p,720p
​
enum<string>
default"9:16"

Streaming frame ratio, which also determines the first-frame image orientation; keeping the two consistent is recommended. Defaults to 9:16 (portrait); when landscape is needed, you must explicitly pass 16:9.

Available options:9:16,16:9
​
string

Derive a new creation from an existing Acting World. Must be an Acting 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.

HappyOyster-Acting-Create World API Reference - QwenCloud