HappyOyster-Acting-Create World API Reference - Alibaba Cloud Model Studio

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.

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).
- 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 Acting World. You do not need to pass mode (the server writes 3; passing a value other than 3 returns 400000). creationModel is always simple, uploadMode is fixed to first_frame, and the enter-room version is fixed to actingV2.

HTTP request

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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-acting/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-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"
    }
}'

First-frame image base64 (async)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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 relaxed conversation on the living-room sofa, with the character naturally looking toward the camera",
    "resolution": "480p",
    "aspectRatio": "9:16",
    "firstFrameImage": {
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
        "referenceType": "default"
    }
}'

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.

creationModel string (Optional)

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

prompt 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.

uploadMode string (Optional)

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

resolution string (Optional)

Video resolution. Defaults to 480p. Allowed values:

480p
720p

aspectRatio string (Optional)

Streaming frame ratio, which also determines the first-frame image orientation; keeping the two consistent is recommended. Defaults to 9:16. Allowed values:

9:16 (portrait): a portrait first frame is recommended
16:9 (landscape): a landscape first frame is recommended

That is, for portrait streaming (9:16) pass a portrait first frame, and for landscape streaming (16:9) pass a landscape first frame. Defaults to 9:16; when landscape is needed, you must explicitly pass aspectRatio=16:9.

refWorldId string (Optional)

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.

firstFrameImage 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
Size: strictly less than 6 MB per image
Aspect ratio: when aspectRatio=9:16, width / height is 0.5–0.667; when aspectRatio=16:9, it is 1.5–2.0
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)

First-frame reference 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
    }
}

Request failed

{
    "code": 400000,
    "message": "Invalid request parameters.",
    "data": null
}

code integer

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

message string

Error message. null on success; a human-readable error message on failure.

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
ready: ready
failed: build failed

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:

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.