Skip to main content
Directing Open API Reference

HappyOyster-Directing-Create World API Reference

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).
  • 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
  • US (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worldsReplace {WorkspaceId} with your actual Workspace ID.

Standard mode (creationModel=simple)

Request parameters

  • Standard mode · plain text (async create)
  • 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": "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"
}'
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)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 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.
eventStyle is not consumed by scriptlist creation; do not pass it.
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.
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:
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.
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:
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 integerReturn code. 0 means success; non-zero is an error code.
message stringError message. null on success.
data objectResponse data. null on failure.

Properties

encryptedWorldId stringEncrypted 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 stringCurrent creation status:
  • generating: building
  • ready: ready
  • failed: build failed
firstFrame stringWorld 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:

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:
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More
HappyOyster-Directing-Create World API Reference - Alibaba Cloud Model Studio