HappyOyster-Directing-查詢 World 構建狀態 API 參考 - Alibaba Cloud Model Studio

查詢 Directing World 的構建進度。接口返回加密 World ID、構建狀態和首幀 URL，客戶端輪詢直至 World 進入 ready。

適用範圍

查詢 Directing World 的構建進度。調用前請確認以下事項：

驗證要求：不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。獲取方式請參閱獲取驗證憑證。
前置條件：使用建立 World介面傳回的 encryptedWorldId 進行查詢。可從 generating 狀態開始查詢。
呼叫方：您的伺服器端或用戶端均可呼叫。

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

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

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

請求參數	查詢 World 構建狀態 `curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-directing/openapi/v1/worlds/build-status?encryptedWorldId={encryptedWorldId}' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY"`
Authorization `string` （必選） API Key 驗證。不強制主 API Key，主 API Key 或臨時 API Key 均可呼叫。主 API Key：以 `sk-` 開頭，如 `sk-xxx`。臨時 API Key：以 `st-` 開頭，如 `st-xxx`。
Query 參數
encryptedWorldId `string` （必選）創建 World接口返回的 Directing 加密 World ID。

回應參數

構建中

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "generating",
        "firstFrame": null
    }
}

構建完成

{
    "code": 0,
    "message": null,
    "data": {
        "encryptedWorldId": "enc_a1b2****",
        "status": "ready",
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "name": "午夜访客",
        "mode": 2
    }
}

code integer

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

message string

錯誤訊息。成功時為 null。

data object

回應資料。失敗時為 null。

屬性

encryptedWorldId string

加密 World ID。

status string

構建狀態：generating / ready / failed。

firstFrame string

World 首幀 URL；尚未產生或構建失敗時為 null。

name string

World 名稱。僅在 status=ready 時返回。

mode integer

Directing 恆為 2。僅 status=ready 時返回。

前置狀態與呼叫注意事項

建議每 3–5 秒輪詢，直到 status 為 ready 或 failed。
只有 ready 的 World 才能換取體驗憑證並進入房間。
URL 圖片在非同步轉存後驗證失敗時，World 可能從 generating 進入 failed。
本接口不返回 aspectRatio。

錯誤碼

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

下一步

World 進入 ready 後：

取得體驗憑證：換取一次性 ticket。
查詢 World 詳情：查詢完整的建立中繼資料。

適用範圍

HTTP 呼叫

新加坡

美国（維吉尼亞）

請求參數

查詢 World 構建狀態

Query 參數

回應參數

構建中

構建完成

前置狀態與呼叫注意事項

錯誤碼

下一步