Skip to main content
Directing Open API Reference

HappyOyster-Directing-Query World Detail API Reference

Query the current status, creation parameters, and returnable ScriptList information of a single Directing World. For build-progress polling, use the Query World Build Status endpoint.

Scope

Query the current status, creation parameters, and returnable ScriptList information of a single Directing World. Before calling, confirm the following:
  • Authentication: Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
  • Prerequisites: Query with the encryptedWorldId returned by Create World. For build-progress polling, use Query World Build Status.
  • Caller: Called by your server.

HTTP request

  • Singapore
  • US (Virginia)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detailReplace {WorkspaceId} with your actual Workspace ID.

Request parameters

  • Query World detail
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY"
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.
Query parameters
encryptedWorldId string (Required)A Directing encrypted World ID under the current primary account. Returned by Create World.

Response parameters

  • Query succeeded (script mode)
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "Midnight Visitor",
        "status": "ready",
        "mode": 2,
        "creationModel": "scriptlist",
        "prompt": null,
        "eventStyle": "normal",
        "perspective": null,
        "uploadMode": null,
        "resolution": "720p",
        "layout": null,
        "narrative": null,
        "refWorldId": null,
        "firstFrameImage": {
            "url": "https://cdn.happyoyster.com/frames/room.png",
            "referenceType": "default"
        },
        "inputImages": null,
        "scriptList": {
            "synopsis": "Late at night, Su Li is startled awake by a knock at the door.",
            "videoTitle": "Midnight Visitor",
            "subjects": [
                {
                    "label": "[character_1]",
                    "name": "Su Li",
                    "type": "character",
                    "refImage": {
                        "url": "https://cdn.happyoyster.com/subjects/suli.png",
                        "referenceType": "default"
                    }
                }
            ],
            "acts": [
                {
                    "turn": 1,
                    "content": "Rain beats against the window, and [character_1] is startled awake from sleep.",
                    "cameraType": "Static",
                    "shotSize": "Wide",
                    "cut": "long-take"
                },
                {
                    "turn": 2,
                    "content": "[character_1] walks toward the door, and the knocking sounds again outside.",
                    "cameraType": "Push-in",
                    "shotSize": "Close-up",
                    "cut": "long-take"
                }
            ]
        },
        "previewUrl": null,
        "aspectRatio": null,
        "createdAt": "2026-06-03T10:00:00Z",
        "updatedAt": "2026-06-03T10:05:00Z"
    }
}
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.name stringWorld name.status stringBuild status: generating / ready / failed.mode integerAlways 2 for Directing.creationModel stringsimple / scriptlist; determines which control endpoints the Travel can call.prompt stringThe Prompt used when creating in simple mode; fixed to null for scriptlist.eventStyle stringThe event style at creation: normal / dramatic / regular.perspective nullUsually null for the Directing model.uploadMode nullUsually null for a Directing World.resolution string480p / 720p.layout stringThe camera-movement style for simple mode; usually null when not passed or for scriptlist.narrative stringThe narrative style for simple mode; usually null when not passed or for scriptlist.refWorldId stringThe encrypted reference World ID used for a derived creation.firstFrameImage objectThe first-frame image at creation; base64 is not returned in the response.inputImages arrayThe reference images persisted when creating in simple mode; scriptlist does not accept this field, so it is usually null.scriptList objectHas a value only for a scriptlist World; null when parsing the structured script fails. Contains synopsis, videoTitle, scene, style, speed, language, setting, soundtrack, prologue, videoTags, subjects (with label/name/type/refImage, etc.), and acts (returned in full according to the stored content, with turn/content/cameraType/shotSize/cut).previewUrl nullCurrently fixed to null.aspectRatio nullFixed to null for the Directing model.createdAt stringCreation time, in ISO 8601 format.updatedAt stringLast update time, in ISO 8601 format.

Prerequisite states and call notes

  • This endpoint can query a generating, ready, or failed World.
  • It does not echo the async field from the creation request.
  • Image fields return only URL and referenceType, and never return base64. The inputImages for simple mode are persisted as reference images and can be returned in the detail; scriptlist does not accept this field.
  • When scriptList parses normally, the full stored structure is returned, and acts is returned in full according to the stored content; when parsing fails, scriptList=null is returned, and an empty acts is not used to indicate a parsing failure.
  • Querying a World from another model, another primary account, or one that has been deleted all return 403001, without revealing whether the resource exists.

Error codes

If the model call fails and returns an error, see HappyOyster Error Codes to resolve it.

Next steps

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