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

Create a real-time directing World. Supports standard mode (natural-language prompt) and script mode (structured ScriptList); 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 a Directing 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 a Directing World. You do not need to pass mode (the server writes 2; passing a value other than 2 returns 400000). creationModel supports simple (standard mode, default) and scriptlist (script mode); the enter-room version is fixed to storyV2, and aspectRatio and maxExperienceTimeSec are fixed to null.

HTTP request

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/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-directing/openapi/v1/worlds

Replace {WorkspaceId} with your actual Workspace ID.

Standard mode (`creationModel=simple`)

Request parameters

Standard mode · plain text (async create)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "First-person (POV) interactive video: the camera simulates my own eyes, locked on a white Maltese puppy directly in front of me — white chef's hat, black-buttoned chef's coat. Soft home-kitchen background, warm light, the puppy's gaze always facing the camera.",
    "resolution": "720p",
    "layout": "Stable",
    "narrative": "Calm"
}'

Standard mode · text + reference image (async create)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "simple",
    "eventStyle": "normal",
    "prompt": "A café by the window. A young woman with long black hair, wearing a beige turtleneck sweater, sits sideways, her left hand propping up her chin as she gazes at the rain-speckled glass window. On the wooden table sits a cup of steaming dark coffee. Outside, warm-yellow street lamps glow in the rainy night; indoors, a single pendant lamp. A quiet rainy night.",
    "resolution": "720p",
    "inputImages": [
        {
            "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
            "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; pass simple for standard mode (default). You provide a natural-language prompt, and the server generates the full 45-beat script, the first frame (which you may provide), and character reference images. After the World is created, you can call the following control endpoints during the Travel phase:

instruct: send text process instructions
pause: pause
resume: resume
rewind: rewind
end: end

See Additional notes for a description of each endpoint.

eventStyle string (Optional)

Applies to creationModel=simple only: selects the script-generation template. Defaults to normal. Allowed values:

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, kept only for backward compatibility with historical inputs; the server parses it as normal. Do not use it in new calls.

refWorldId string (Optional)

Derive a new creation from an existing Directing World. Must be a Directing encrypted World ID under the current primary account; a World from another model or another primary account returns 403001.

prompt string (Required)

World theme description; Chinese and English are supported. Non-empty, up to 2000 characters.

resolution string (Required)

Video resolution. Allowed values:

480p
720p

layout string (Optional)

Camera movement style (how the camera moves and how hard it cuts). Allowed values:

Stable: steady camera, little movement, favoring continuous long takes with sparse cuts
Fast: fast camera, strong momentum, with denser hard cuts / rapid zooms / shot-size jumps
Calm: between the two, a restrained camera that is neither rushed nor aggressive

narrative string (Optional)

Narrative style (how dense the drama is and how strong the emotion is). Allowed values:

Calm: few events, favoring atmosphere and slow progression
Dramatic: dense events, with more pronounced reactions / reversals / obstacles and high tension
Normal: regular narrative density, a middle tier
Steady: even pacing without piling up climaxes, close to Normal

firstFrameImage object (Optional)

When provided, it is reused directly as the World's first frame, skipping AI first-frame generation. 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. 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. 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.

inputImages array (Optional)

Used for script generation and character reference images, up to 6 images, independent of firstFrameImage. For each array item, 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)

Image URL. Constraints:

Must be a valid http / https URL with a host, accessible by the server
The actual format, size, and 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)

Image base64. Constraints:

A complete data URI data:image/<subtype>;base64,<payload> is recommended
Format, size, and aspect ratio are validated synchronously at the creation entry point

referenceType string (Optional)

Reference-image type. Defaults to default.

Script mode (`creationModel=scriptlist`)

Request parameters

Script mode (async create)

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "async": true,
    "creationModel": "scriptlist",
    "resolution": "720p",
    "firstFrameImage": {
        "url": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/common/images/6a4b3c2d1e0f9fc7.png",
        "referenceType": "default"
    },
    "scriptList": {
        "videoTitle": "Su Nian · Sitting with You for a While Tonight",
        "synopsis": "The young girl Su Nian sits at a light-colored desk facing the camera, chatting with you slowly and helping you let go of the day.",
        "subjects": [
            {
                "label": "[character_1]",
                "name": "Su Nian",
                "type": "character",
                "gender": "female",
                "age": "young girl",
                "ethnicity": "East Asian",
                "appearance": "medium-length straight black hair with a side part, a rounded face, a cream-white knit top, anime style, clean lines",
                "position": "center of the frame, seated at a light-colored desk",
                "voice": "gentle girlish voice, slightly slow pace, moderate volume"
            }
        ],
        "acts": [
            {
                "turn": 1,
                "content": "[character_1] sits at the light-colored desk facing the camera, leaning slightly forward, eyes curving as she softly says, \"Hey, I'll sit with you for a while again tonight, let's chat slowly.\"",
                "cameraType": "Push-in",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 2,
                "content": "[character_1] folds her hands on the desk, nods gently, and says, \"Let's set aside all the worries of the day for now.\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            },
            {
                "turn": 3,
                "content": "[character_1] tilts her head slightly, looking at the camera with a gentle expression, and asks, \"How was your day? Are you okay, are you tired?\"",
                "cameraType": "Static",
                "shotSize": "Medium",
                "cut": "long-take"
            }
        ]
    }
}'

Content-Typestring(Required)

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

Authorization string (Required)

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; pass scriptlist for script mode. You provide the structured script, and the server no longer generates a script — it only assembles and persists it. After the World is created, you can call the following control endpoints during the Travel phase:

update-script: fully replace the script
pause: pause
resume: resume
rewind: rewind
end: end

instruct (send text process instructions) is not supported. See Additional notes for a description of each endpoint.

Note

eventStyle is not consumed by scriptlist creation; do not pass it.

refWorldId string (Optional)

resolution string (Required)

Video resolution. Allowed values:

480p
720p

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

scriptList object (Required)

Structured script. Must include synopsis and a non-empty acts.

Properties

synopsis string (Required)

Story synopsis. Non-empty, up to 2000 characters.

videoTitle string (Optional)

World name. Defaults to New World, up to 128 characters.

scene string (Optional)

Scene setting. Defaults to Static Shot, up to 64 characters.

style string (Optional)

Visual style. Defaults to Stable, up to 64 characters.

speed string (Optional)

Narrative pacing. Defaults to Steady, up to 64 characters.

language string (Optional)

Script language. Defaults to en (English); pass zh for Chinese. Up to 64 characters.

setting string (Optional)

Worldview or background setting. Up to 2000 characters.

soundtrack string (Optional)

Soundtrack description. Up to 500 characters.

prologue string (Optional)

Opening prologue. Up to 1000 characters.

videoTags array<string> (Optional)

Video tags. Up to 20 tags, each up to 32 characters.

subjects array<object> (Optional)

Predefined subjects, up to 6. Each array item contains the following properties:

subjects[] properties

label string (Optional)

References a subject in acts[].content. Formatted as [character_x], assigned in array order by default.

name string (Optional)

Human-readable name, not rendered as on-screen text. Up to 64 characters.

type string (Optional)

Subject type. Defaults to character. Determines the subject's appearance and how the other properties are filled in. Allowed values:

character: human character (default). Fill in gender / position / ethnicity / age / appearance as for a person.
animal: real animal (cat, dog, horse, etc.). Use species instead of gender and subspecies / breed instead of ethnicity.
creature: non-human / fantasy creature (dragon, monster, alien, etc.). Fill in for a non-human appearance likewise.
narrator: narrator / voice-over. Voice only, does not appear on screen; fill in voice and no reference image is produced.

refImage object (Optional)

Subject reference image; url and base64 are mutually exclusive (choose one), and the image must be strictly less than 6 MB.

refImage properties

url string (Conditionally required)

Subject reference image URL.

base64 string (Conditionally required)

Subject reference image base64.

referenceType string (Optional)

Reference-image type. Defaults to default.

gender string (Optional)

Gender description. Up to 64 characters.

position string (Optional)

On-screen position. Up to 64 characters.

ethnicity string (Optional)

Ethnicity or race description. Up to 64 characters.

age string (Optional)

Age description. Up to 64 characters.

appearance string (Optional)

Appearance details. Up to 500 characters.

voice string (Optional)

Voice, speaking rate, and volume description. Up to 200 characters.

acts array<object> (Required)

Beat-by-beat script, 1–45 entries, with all content totaling no more than 100000 characters. Each array item contains the following properties:

acts[] properties

turn int (Optional)

Turn number. 1–45, no duplicates, incrementing from 1 in array order by default.

content string (Required)

Script for this beat. Non-empty, up to 2000 characters per beat; can reference subjects with [character_x].

cameraType string (Optional)

Camera type (how the camera shoots). Defaults to Static. Allowed values:

Static: camera locked in place, no push or swivel (default). Shot size is controlled by shotSize: wide / medium / close
Tracking: tracking shot. The camera follows the subject, keeping the tracking distance
Pan Left: camera stays put, panning left
Pan Right: camera stays put, panning right
Tilt Up: camera tilts up
Tilt Down: camera tilts down
Push-in: optical / physical push-in, the frame gradually gets closer
Pull-out: pull out, the frame gradually widens
POV Forward: first person, the camera is the eyes, walking forward
POV Look Down: first person looking down
POV Look Up: first person looking up
POV Turn Left: first person turning left to look
POV Turn Right: first person turning right to look

shotSize string (Optional)

Shot size. Defaults to Medium. Determines how much detail this beat can carry; change shot size via cuts, and do not describe both the full body and fingertips in the same beat. Allowed values:

Wide: wide / full shot, including the full body and its relation to the environment. Suitable for blocking, positioning, and spatial staging; do not describe micro-expressions or fingertips.
Medium: medium shot (default), upper-body posture and gestures. Suitable for dialogue and everyday actions; do not describe foot blocking or fine hand operations.
Close-up: close-up, one face / one hand / one prop. Suitable for expressions and key details; do not describe full-body movement.

Pairing with cuts: to see more detail, first cut-in to Close-up, then cut-out back to a wide shot; use long-take for most beats to hold the same shot size and avoid jumping shot sizes back and forth.

cut string (Optional)

Cut method (how this beat cuts in). Defaults to long-take. Allowed values:

long-take: no cut, continuing from the previous shot. Default and the most stable
hard-cut: hard cut, instantly switching to another shot. Use this for shot / reverse-shot dialogue
cut-in: cut to a closer shot size, e.g. Medium → Close-up. Use for viewing details and cutting into hand interactions
cut-out: cut to a wider shot size, e.g. Close-up → Medium / Wide
cutaway: briefly cut to a detail outside the main line
cutback: cut back to the main subject from a cutaway. Can only follow a cutaway
camera movement transition: connect two segments with rapid camera movement rather than a hard cut

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

Encrypted World ID, returned in both synchronous and asynchronous modes. This value is used for subsequent build-status queries, World detail queries, and exchanging an experience credential.

status string

Current creation status:

generating: building
ready: ready
failed: build failed

firstFrame string

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

Additional notes

Character counting: The "up to N characters" limits in this document are counted by character (Unicode characters), regardless of Chinese or English — Chinese characters, English letters, digits, spaces, and punctuation each count as 1 character.
ScriptList submission requirements: When creating a World, acts is limited to 45 entries but is not required to be exactly 45; the full 45 entries are only required when calling update-script during Travel.
Travel control endpoints: The endpoint names listed under creationModel are server-side endpoints that can be called during the Travel phase after the World is created, not enum values for this endpoint's input. Their meanings are as follows:
- instruct: send text process instructions to a running Travel; standard mode only.
- pause: pause the Travel.
- resume: resume playback.
- rewind: rewind to a specified time point; requires pausing first.
- end: end the Travel.
- update-script: fully replace the script; script mode only.

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 and ScriptList.

Scope

HTTP request

Singapore

US (Virginia)

Standard mode (creationModel=simple)

Request parameters

Standard mode · plain text (async create)

Standard mode · text + reference image (async create)

Request Body

Script mode (creationModel=scriptlist)

Request parameters

Script mode (async create)

Request Body

Response parameters

Async create

Additional notes

Error codes

Next steps

Standard mode (`creationModel=simple`)

Script mode (`creationModel=scriptlist`)