Skip to main content

HappyOyster-Acting-取得體驗憑證 API 參考

第三方伺服器端使用主 API Key 換取短時效、一次性的 ticket，再將其安全下發給用戶端。此介面僅驗證 World 歸屬、狀態與規格，不會建立 Travel。

適用範圍

第三方伺服器端使用主 API Key 換取短效期、一次性的 ticket，再將其安全下發給用戶端。呼叫前請確認以下事項：
  • 驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
  • 前置條件：World 必須屬於當前主帳號與 Acting 模型，且狀態為 ready。可透過查詢 World 建置狀態介面確認。
  • 呼叫方：由您的伺服器端呼叫，換得的 ticket 應僅下發給準備立即進房的用戶端。

HTTP 呼叫

  • 新加坡
  • 美国（維吉尼亞）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds/get-travel-credential呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。

請求參數

  • 獲取體驗憑證
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds/get-travel-credential' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedWorldId": "{encryptedWorldId}"
}'
Content-Typestring（必選）請求內容類型。此參數必須設定為 application/json。
Authorization string （必選）API Key 驗證。僅支援 主 API Key，以 sk- 開頭，例如 sk-xxx。通常設定為環境變數 $DASHSCOPE_API_KEY。若使用臨時 API Key（以 st- 開頭）進行呼叫，將返回 403003。
請求主體（Request Body）
encryptedWorldId string （必選）當前主帳號名下、狀態為 ready 的 Acting World ID。由建立 World介面返回。

回應參數

  • 換取成功
{
    "code": 0,
    "message": null,
    "data": {
        "ticket": "tk_a1b2****",
        "expiresIn": 1800,
        "encryptedWorldId": "enc_a1b2****"
    }
}
code integer返回碼。0 表示成功，非 0 為錯誤碼。
message string錯誤訊息。成功時為 null。
data object回應資料。失敗時為 null。

屬性

ticket string前綴為 tk_ 的一次性 Travel 憑證。有效期 1800 秒（30 分鐘），且只能成功使用一次。expiresIn integer有效期秒數，固定為 1800，即 30 分鐘。encryptedWorldId string憑證對應的加密 World ID。

前置狀態與呼叫注意事項

  • World 必須屬於當前主帳號與 Acting 模型，且狀態為 ready。
  • ticket 有效期為 1800 秒且只能成功使用一次；過期或已使用後須重新換取。
  • ticket 應僅下發給準備立即進房的用戶端，不應持久化為長期存取憑證。
  • 呼叫本介面不會建立 Travel；Travel 在進入房間成功時建立。
  • Acting 功能閘主要在建立和進房時生效；換取憑證仍會驗證 World 對應規格，規格未開通時返回 403007。

錯誤碼

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

下一步

換取 ticket 後：