HappyOyster-Directing-查詢 World 詳情 API 參考 - Alibaba Cloud Model Studio

查詢單個 Directing World 的當前狀態、創建參數和可返回的 ScriptList 資訊。構建進度輪詢請使用查詢 World 構建狀態接口。

適用範圍

查詢單個 Directing World 的當前狀態、創建參數和可返回的 ScriptList 資訊。調用前請確認以下事項：

驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
- 取得主 API Key：取得與設定 API Key。
前置條件：使用建立 World介面返回的 encryptedWorldId 查詢。構建進度輪詢應使用查詢 World 構建狀態。
呼叫方：您的伺服器端呼叫。

HTTP 呼叫

新加坡

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

美国（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/detail

呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數	查詢 World 詳情 `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` （必選） API Key 驗證。僅支援主 API Key，以 `sk-` 開頭，如 `sk-xxx`。通常設定為環境變數 `$DASHSCOPE_API_KEY`。臨時 API Key（`st-` 開頭）呼叫會返回 `403003`。
Query 參數
encryptedWorldId `string` （必選）當前主帳號名下的 Directing 加密 World ID。由創建 World接口返回。

回應參數

查詢成功（劇本模式）

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "name": "午夜访客",
        "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": "深夜，苏黎被敲门声惊醒。",
            "videoTitle": "午夜访客",
            "subjects": [
                {
                    "label": "[character_1]",
                    "name": "苏黎",
                    "type": "character",
                    "refImage": {
                        "url": "https://cdn.happyoyster.com/subjects/suli.png",
                        "referenceType": "default"
                    }
                }
            ],
            "acts": [
                {
                    "turn": 1,
                    "content": "雨水拍打窗户，[character_1] 从睡梦中惊醒。",
                    "cameraType": "Static",
                    "shotSize": "Wide",
                    "cut": "long-take"
                },
                {
                    "turn": 2,
                    "content": "[character_1] 走向房门，门外再次响起敲门声。",
                    "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 integer

返回碼。0 表示成功，非 0 為錯誤碼。

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedWorldId string

加密 World ID。

name string

World 名稱。

status string

構建狀態：generating / ready / failed。

mode integer

Directing 恆為 2。

creationModel string

simple / scriptlist；決定 Travel 可调用的控制接口。

prompt string

simple 模式創建時的 Prompt；scriptlist 固定為 null。

eventStyle string

創建時的事件風格：normal / dramatic / regular。

perspective null

Directing 模型通常為 null。

uploadMode null

Directing World 通常為 null。

resolution string

480p / 720p。

layout string

simple 模式的鏡頭運動風格；未傳或 scriptlist 時通常為 null。

narrative string

simple 模式的敘事風格；未傳或 scriptlist 時通常為 null。

refWorldId string

衍生創建時使用的加密參考 World ID。

firstFrameImage object

建立時的首幀圖；回應不返回 base64。

inputImages array

simple 模式創建時持久化的參考圖；scriptlist 不接受該欄位，通常為 null。

scriptList object

僅 scriptlist World 有值；結構化劇本反解失敗時為 null。含 synopsis、videoTitle、scene、style、speed、language、setting、soundtrack、prologue、videoTags、subjects（含 label/name/type/refImage 等）、acts（按已存內容完整返回，含 turn/content/cameraType/shotSize/cut）。

previewUrl null

目前固定為 null。

aspectRatio null

Directing 模型固定為 null。

createdAt string

建立時間，ISO 8601 格式。

updatedAt string

最近更新時間，ISO 8601 格式。

前置狀態與呼叫注意事項

本接口可查詢 generating、ready 或 failed World。
不回顯創建請求中的 async。
圖片欄位只返回 URL 和 referenceType，不會回傳 base64。simple 模式的 inputImages 會作為參考圖持久化並可在詳情中返回；scriptlist 不接受該欄位。
scriptList 正常反解時返回已儲存的完整結構，acts 按已存內容完整返回；反解失敗時返回 scriptList=null，不會用空 acts 表示反解失敗。
查詢其它模型、其它主帳號或已刪除的 World 均返回 403001，不會洩漏資源是否存在。

錯誤碼

如果模型呼叫失敗並返回錯誤訊息，請參閱 HappyOyster 錯誤碼進行解決。

下一步

查詢 World 列表：分頁查詢所有 Directing World。
刪除 World：刪除不再使用的 World。
World 為 ready 時可取得體驗憑證。

適用範圍

HTTP 呼叫

新加坡

美国（維吉尼亞）

請求參數

查詢 World 詳情

Query 參數

回應參數

查詢成功（劇本模式）

前置狀態與呼叫注意事項

錯誤碼

下一步