Skip to main content

HappyOyster-Adventure-查詢 World 建置狀態 API 參考

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

適用範圍

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

HTTP 呼叫

  • 新加坡
  • 华北2（北京）
  • 美国（維吉尼亞）
GET https://{WorkspaceId}.ap-southeast-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 integer返回碼。0 表示成功，非 0 為錯誤碼。
message string錯誤訊息。成功時為 null。
data object回應資料。失敗時為 null。

屬性

encryptedWorldId string加密 World ID。status string構建狀態：
  • generating：建立中
  • ready：就緒，可換取體驗憑證並進房
  • failed：建立失敗
firstFrame stringWorld 首幀 URL；尚未產生或構建失敗時為 null。name stringWorld 名稱。僅在 status=ready 時返回。mode integerAdventure 恆為 1。僅於 status=ready 時傳回。

前置狀態與呼叫注意事項

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

錯誤碼

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

下一步

World 進入 ready 後：