Skip to main content
Acting Open API Reference (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.

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

Request parameters

  • First-frame image (async)
  • 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 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"
    }
}'
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
  • Request failed
{
    "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; a human-readable error message on failure.
data objectResponse data. null on failure.

Properties

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