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

查詢 Acting World 的構建進度。介面返回加密 World ID、構建狀態和首幀 URL，用戶端輪詢直至 World 進入 ready。

適用範圍

查詢 Acting World 的構建進度。呼叫前請確認以下事項：

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

HTTP 呼叫

新加坡

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

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

美国（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/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-acting/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`。通常設定為環境變數 `$DASHSCOPE_API_KEY`。臨時 API Key：以 `st-` 開頭，如 `st-xxx`。
Query 參數
encryptedWorldId `string` （必選）建立 World介面返回的 Acting 加密 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/acting_world_xyz789.jpg",
        "name": "深夜视频通话",
        "mode": 3
    }
}

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

Acting 恆為 3。僅在 status=ready 時返回。

前置狀態與呼叫注意事項

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

錯誤碼

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

下一步

World 進入 ready 後可進行以下操作：

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

適用範圍

HTTP 呼叫

新加坡

美国（維吉尼亞）

請求參數

查詢 World 構建狀態

Query 參數

回應參數

構建中

構建完成

前置狀態與呼叫注意事項

錯誤碼

下一步