HappyOyster-Adventure-查詢 World 建置狀態 API 參考 - Alibaba Cloud Model Studio

查詢 Adventure World 的建置進度。介面會傳回加密 World ID、建置狀態與首訊框 URL，用戶端需輪詢直至 World 進入 ready。

適用範圍

查詢 Adventure 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-adventure/openapi/v1/worlds/build-status

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

华北2（北京）

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/build-status

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

美国（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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-adventure/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介面傳回的加密 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": 1
    }
}

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

Adventure 恆為 1。僅於 status=ready 時傳回。

前置狀態與呼叫注意事項

建議每 3–5 秒輪詢，直到 status 為 ready 或 failed。
只有 ready 的 World 才能換取體驗憑證並進入房間。
URL 圖片在非同步轉存後驗證失敗時，World 可能從 generating 進入 failed。
本介面不返回 aspectRatio；需要 perspective、uploadMode 等建立中繼資料時，請呼叫查詢 World 詳細資料。

錯誤碼

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

下一步

World 進入 ready 後：

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

適用範圍

HTTP 呼叫

新加坡

华北2（北京）

美国（維吉尼亞）

請求參數

查詢 World 構建狀態

Query 參數

回應參數

構建中

構建完成

前置狀態與呼叫注意事項

錯誤碼

下一步