Skip to main content

HappyOyster-Directing-查詢 World 構建狀態 API 參考

查詢 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。

請求參數

  • 查詢 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 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 integerDirecting 恆為 2。僅 status=ready 時返回。

前置狀態與呼叫注意事項

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

錯誤碼

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

下一步

World 進入 ready 後：