HappyOyster-Directing-Create World API Reference

POST

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

curl --location 'https://dashscope-intl.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\u2019s hat, black-buttoned chef\u2019s coat. Soft home-kitchen background, warm light, the puppy\u2019s gaze always facing the camera.",
  "resolution": "720p",
  "layout": "Stable",
  "narrative": "Calm"
}'

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

Scope

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 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 and scriptlist; the enter-room version is fixed to storyV2, and aspectRatio and maxExperienceTimeSec are fixed to null.

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

enum<string>

required

Video resolution.

Available options:480p,720p

boolean

defaulttrue

Whether to create asynchronously. Defaults to true. true: returns immediately; the World builds in the background. false: the server polls every 3 seconds for up to 120 seconds and returns when the build completes.

enum<string>

default"simple"

Creation sub-mode. simple (standard mode, default): natural-language prompt, the server generates the full script. scriptlist (script mode): structured script provided by the user.

Available options:simple,scriptlist

enum<string>

default"normal"

Event style, used to select the script-generation template. Defaults to normal.

Available options:normal,dramatic,regular

string

Derive a new creation from an existing Directing World. Must be a Directing encrypted World ID under the current primary account.

string

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

enum<string>

Camera movement style. Optional for simple mode.

Available options:Stable,Fast,Calm

enum<string>

Narrative style. Optional for simple mode.

Available options:Calm,Dramatic,Normal,Steady

object

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

Image URL. Mutually exclusive with base64. Must be a valid http/https URL with a host, accessible by the server.

string

Image base64. Mutually exclusive with url. A complete data URI data:image/<subtype>;base64,<payload> is recommended.

string

default"default"

Reference-image type. Defaults to default.

object[]

Used for script generation and character reference images, up to 6 images, independent of firstFrameImage. Optional for simple mode.

Show child attributes

string

Image URL. Mutually exclusive with base64. Must be a valid http/https URL with a host, accessible by the server.

string

Image base64. Mutually exclusive with url. A complete data URI data:image/<subtype>;base64,<payload> is recommended.

string

default"default"

Reference-image type. Defaults to default.

object

Structured script. Required for scriptlist mode. Must include synopsis and a non-empty acts.

Show child attributes

string

required

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

object[]

required

Beat-by-beat script, 1-45 entries, with all content totaling no more than 100000 characters.

Show child attributes

string

required

Script for this beat. Non-empty, up to 2000 characters per beat.

integer

Turn number. 1-45, no duplicates.

enum<string>

default"Static"

Camera type. Defaults to Static.

Available options:Static,Tracking,Pan Left,Pan Right,Tilt Up,Tilt Down,Push-in,Pull-out,POV Forward,POV Look Down,POV Look Up,POV Turn Left,POV Turn Right

enum<string>

default"Medium"

Shot size. Defaults to Medium.

Available options:Wide,Medium,Close-up

enum<string>

default"long-take"

Cut method. Defaults to long-take.

Available options:long-take,hard-cut,cut-in,cut-out,cutaway,cutback,camera movement transition

string

default"New World"

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

string

default"Static Shot"

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

string

default"Stable"

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

string

default"Steady"

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

string

default"en"

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

string

Worldview or background setting. Up to 2000 characters.

string

Soundtrack description. Up to 500 characters.

string

Opening prologue. Up to 1000 characters.

string[]

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

object[]

Predefined subjects, up to 6.

Show child attributes

string

References a subject in acts[].content. Formatted as [character_x].

string

Human-readable name. Up to 64 characters.

enum<string>

default"character"

Subject type. Defaults to character.

Available options:character,animal,creature,narrator

object

Show child attributes

string

Image URL. Mutually exclusive with base64. Must be a valid http/https URL with a host, accessible by the server.

string

Image base64. Mutually exclusive with url. A complete data URI data:image/<subtype>;base64,<payload> is recommended.

string

default"default"

Reference-image type. Defaults to default.

string

Gender description. Up to 64 characters.

string

On-screen position. Up to 64 characters.

string

Ethnicity or race description. Up to 64 characters.

string

Age description. Up to 64 characters.

string

Appearance details. Up to 500 characters.

string

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

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 server-generated encrypted World ID.

enum<string>

Current creation status: generating/ready/failed.

Available options:generating,ready,failed

string

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

​Scope

Authorizations

Header Parameters

Body

Response

Scope