Skip to main content

HappyOyster-Directing-查詢 World 詳情 API 參考

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

適用範圍

查詢單個 Directing World 的當前狀態、創建參數和可返回的 ScriptList 資訊。調用前請確認以下事項：
  • 驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
  • 前置條件：使用建立 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。

請求參數

  • 查詢 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 stringWorld 名稱。status string構建狀態：generating / ready / failed。mode integerDirecting 恆為 2。creationModel stringsimple / scriptlist；決定 Travel 可调用的控制接口。prompt stringsimple 模式創建時的 Prompt；scriptlist 固定為 null。eventStyle string創建時的事件風格：normal / dramatic / regular。perspective nullDirecting 模型通常為 null。uploadMode nullDirecting World 通常為 null。resolution string480p / 720p。layout stringsimple 模式的鏡頭運動風格；未傳或 scriptlist 時通常為 null。narrative stringsimple 模式的敘事風格；未傳或 scriptlist 時通常為 null。refWorldId string衍生創建時使用的加密參考 World ID。firstFrameImage object建立時的首幀圖；回應不返回 base64。inputImages arraysimple 模式創建時持久化的參考圖；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 nullDirecting 模型固定為 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 錯誤碼進行解決。

下一步