Directing

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.

GET

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

cURL - Query World detail

curl --location 'https://dashscope-intl.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

{
  "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"
  }
}

Scope

Only the primary API Key is supported; temporary API Keys cannot be used (error code 403003).
For build-progress polling, use Query World Build Status instead.

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

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

string

required

A Directing encrypted World ID under the current primary account.

Response

200-application/json

integer

string

object

Show child attributes

string

enum<string>

Available options:generating,ready,failed

integer

Always 2 for Directing.

enum<string>

Available options:simple,scriptlist

string

The Prompt used in simple mode; null for scriptlist.

enum<string>

Available options:normal,dramatic,regular

string

Usually null for the Directing model.

string

Usually null for a Directing World.

enum<string>

Available options:480p,720p

string

object

The first-frame image at creation; base64 is not returned.

unknown[]

Reference images persisted in simple mode; null for scriptlist.

object

Has a value only for scriptlist; null when parsing fails.

string

Fixed to null.

string

Fixed to null for the Directing model.

string

cURL - Query World detail

curl --location 'https://dashscope-intl.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail?encryptedWorldId={encryptedWorldId}' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

{
  "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"
  }
}

HappyOyster-Directing-Query World Detail API Reference - QwenCloud

​Scope

Authorizations

Header Parameters

Query Parameters

Response

Scope