HappyOyster-Adventure-取得體驗憑證 API參考 - Alibaba Cloud Model Studio

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

適用範圍

第三方伺服器端使用主 API Key 換取短效期、一次性的 ticket，再將其安全下發給用戶端。呼叫前請確認以下事項：

驗證要求：僅支援 主 API Key 呼叫，臨時 API Key 無法使用（錯誤碼 403003）。
- 取得主 API Key：取得與設定 API Key。
前置條件：World 必須屬於目前主帳號和 Adventure 模型，且狀態為 ready。可透過查詢World建置狀態介面確認。
呼叫方：由您的伺服器端呼叫，換得的 ticket 應僅下發給準備立即進房的用戶端。

HTTP 呼叫

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/get-travel-credential

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

华北2（北京）

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/worlds/get-travel-credential

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

美国（維吉尼亞）

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/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-adventure/openapi/v1/worlds/get-travel-credential' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "encryptedWorldId": "{encryptedWorldId}" }'`
Content-Type`string`（必選）請求內容類型。此參數必須設定為 `application/json`。
Authorization `string` （必選） API Key 驗證。僅支援主 API Key，以 `sk-` 開頭，例如 `sk-xxx`。通常設定為環境變數 `$DASHSCOPE_API_KEY`。若使用臨時 API Key（以 `st-` 開頭）進行呼叫，將返回 `403003`。
請求主體（Request Body）
encryptedWorldId `string` （必選）目前主帳號名下、狀態為 `ready` 的 Adventure 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 必須為 ready。
ticket 有效期為 30 分鐘且只能成功使用一次；過期或已使用後須重新換取。
ticket 應僅下發給準備立即進房的用戶端，不應持久化為長期存取憑證。
呼叫本介面不會建立 Travel；Travel 在進入房間成功時建立。
未購買該 World 對應規格時返回 403007；容量配置暫不可用時返回 403008。

錯誤碼

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

下一步

換取 ticket 後：

用戶端進入房間：用戶端使用 ticket 建立 Travel 並獲取 RTC 設定。

適用範圍

HTTP 呼叫

新加坡

华北2（北京）

美国（維吉尼亞）

請求參數

獲取體驗憑證

請求主體（Request Body）

回應參數

換取成功

前置狀態與呼叫注意事項

錯誤碼

下一步